Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ Every command supports `--json` for piping into `jq` or Claude.
| `mna trips list [--status=planning\|ready\|finished\|cancelled] [--include-example]` | List trips. |
| `mna trips show <tripId> [--all-options]` | Show one trip in detail: each variant's party, plus an accommodation table per variant (cost, guest rating in its source scale, facilities). By default only the selected variant and its selected options; `--all-options` adds the unselected variants and options. |
| `mna trips create --name <name> [--cover-photo <url>]` | Create a new trip. |
| `mna trips edit <tripId> [--name=...] [--cover-photo=...] [--status=...]` | Update trip-level fields. |
| `mna trips edit <tripId> [--name=...] [--cover-photo=...] [--status=...] [--budget=<json>]` | Update trip-level fields. `--budget` is owner only, and `--budget null` clears it. |
| `mna trips delete <tripId> [--yes]` | Delete a trip permanently. |
| `mna trips share <tripId>` | Generate a shareable link for the trip. |
| `mna trips unshare <tripId>` | Revoke all share links. |
Expand Down Expand Up @@ -268,8 +268,8 @@ selected variant; add `--all-options` to include the other variants.

| Command | Description |
|---|---|
| `mna options add <tripId> <variantId> <destinationKey> <kind> --from-json=<file> [--free-cancellation-until=<date>]` | Add an option from JSON. `--free-cancellation-until` (accommodation only) merges into the body. |
| `mna options edit <tripId> <variantId> <destinationKey> <kind> <optionKey> [--from-json=<file>] [--free-cancellation-until=<date>]` | Edit an option. For accommodation, `--free-cancellation-until` alone updates the date without a JSON file. |
| `mna options add <tripId> <variantId> <destinationKey> <kind> --from-json=<file> [--free-cancellation-until=<date>] [--details=<json>] [--photos=<json>] [--website=<url>]` | Add an option from JSON. `--free-cancellation-until`, `--details` and `--photos` (accommodation only) merge into the body. |
| `mna options edit <tripId> <variantId> <destinationKey> <kind> <optionKey> [--from-json=<file>] [--free-cancellation-until=<date>] [--details=<json>] [--photos=<json>] [--website=<url>]` | Edit an option. For accommodation, each flag works alone, without a JSON file. `--details` changes only the properties it names; `--photos` replaces the list. |
| `mna options delete <tripId> <variantId> <destinationKey> <kind> <optionKey> [--yes]` | Delete an option. |
| `mna options select <tripId> <variantId> <destinationKey> <kind> <optionKey>` | Select an option. |
| `mna options deselect <tripId> <variantId> <destinationKey> <kind>` | Deselect the current option. |
Expand Down
12 changes: 12 additions & 0 deletions skills/mna/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,18 @@ The app renders and totals these fields; misuse degrades the plan quietly.
independently, and can't be sorted or compared.
- **Ratings keep their source's scale.** Store `externalRating.scale` beside the score (out of
10, out of 5) and quote the pair. Never normalise, and never rank a /10 score against a /5 one.
- **`stayDetails` exists to help the group choose between this trip's options.** Add a property
only when it separates this option from the others. Never record what is equally true of all
of them: if every option is central, say nothing about being central. Never invent or infer a
fact: leave it out when unknown, and put what still needs confirming in `worthChecking`. Say
where a fact came from in `sourceNote` when that isn't obvious, and set `author` to `agent`.
`skiBack` needs the listing, the owner or a piste map behind it, never a guess from distance.
Keep prices out of these fields, because they appear on share links that hide prices.
- **`photos` are only images the owner may use**: their own, or ones the property allows to be
reused. Don't copy a gallery from a booking site or from search results.
- **`budget` is the owner's number.** Set it only when the owner has stated one.
- **`priceOptions` on an event are real alternatives** with real prices, such as 4-day and 6-day
ski passes. `totalCost` stays the price the totals use.
- **The user's edits are authoritative.** A hand-corrected price, a fixed location or spelling —
keep it, and don't revert to the scraped value on the next sync.

Expand Down
45 changes: 43 additions & 2 deletions skills/mna/references/cli-and-schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ variants add <trip> --name <dates…> [--adults --child-ages --no-children -
destinations add <trip> <var> --place [--start-date --end-date --notes --return-to-home]
edit <trip> <var> <destKey> [--place --notes --start-date --end-date --return-to-home/--no-…]
reorder <trip> <var> --order=k1,k2,k3 | delete <trip> <var> <destKey>
options add <trip> <var> <destKey> <kind> --from-json <file> [--free-cancellation-until <date>]
edit <trip> <var> <destKey> <kind> <optKey> [--from-json <file>] [--free-cancellation-until <date>]
options add <trip> <var> <destKey> <kind> --from-json <file> [--free-cancellation-until <date>] [--details <json>] [--photos <json>] [--website <url>]
edit <trip> <var> <destKey> <kind> <optKey> [--from-json <file>] [--free-cancellation-until <date>] [--details <json>] [--photos <json>] [--website <url>]
select <trip> <var> <destKey> <kind> <optKey> | deselect <trip> <var> <destKey> <kind>
delete <trip> <var> <destKey> <kind> <optKey>
events add <trip> <var> --from-json <file> | edit <trip> <var> <eventKey> --from-json
Expand Down Expand Up @@ -65,6 +65,38 @@ property level, which is not what a user means by "an apartment with a kitchen".
Put ratings and facilities in these fields rather than in `notes` — `mna trips show` renders them,
and `notes` should carry what no field covers. `type` and `roomDetails` come back on read too.

#### `stayDetails` and `photos`

Set these inside the `--from-json` body, or with the flags on `options add` and `options edit`:

```bash
mna options edit <trip> <var> <destKey> accommodation <optKey> \
--details '{"highlight":"Only one with a private sauna","kitchen":"private","parking":"Garage, book ahead","sourceNote":"Listing page, Oct 2026","author":"agent"}' \
--photos '[{"url":"https://…/balcony.jpg","credit":"Owner"}]'
```

All `stayDetails` properties are optional. Add one only when it helps choose between this trip's
options, and leave out anything equally true of all of them, or unknown.

| Property | Value |
|---|---|
| `highlight` | one line, up to 160 characters |
| `worthChecking` | list of up to 10 things to confirm before booking; hidden on share links that hide notes |
| `kitchen` | `private` \| `shared` \| `none` |
| `breakfast` | `included` \| `available` \| `none` |
| `skiBack` | `yes` \| `partly` \| `no`, only when confirmed |
| `bookability` | `bookable` \| `on_request` \| `price_unconfirmed` |
| `author` | `owner` \| `agent` \| `sonnet`; agents set `agent` |
| `bedrooms`, `bathrooms`, `maxGuests`, `sizeInM2` | numbers |
| `dinner`, `bedLayout`, `skiBackNote`, `mainLiftName`, `skiStorage`, `kidsFacilities`, `wellness`, `pool`, `beach`, `parking`, `noise`, `view`, `airConditioning`, `laundry`, `accessibility`, `pets`, `sourceNote` | text, up to 300 characters |

On an edit, only the `stayDetails` properties you send change. `null` clears one, and
`--website` is the place's own official site, never a booking or listing site; leave it out if you can't confirm it. Photos from it may then be linked automatically, credited to the site. `--website null` clears it. `--details null` clears them all. `--photos` replaces the whole list, up to 12 photos, and
`--photos null` clears it. Unknown properties are rejected.

`photos` take `{ "url", "credit"?, "creditUrl"? }`. Each URL must be a directly linkable http or
https image that the owner may use.

### transport
```json
{
Expand Down Expand Up @@ -93,6 +125,15 @@ home-return drive on the `--return-to-home` destination so the per-variant total
"location": { "name": "Old Town", "formattedAddress": "…", "coordinates": { "lat": 0.0, "lng": 0.0 } } }
```

When the group has a real choice of price, add `"priceOptions": [{ "label": "4-day pass", "totalCost": 200 }, { "label": "6-day pass", "totalCost": 280 }]`,
up to 10, in the event's `currency`. On `events edit`, the list is replaced, and `null` clears it.

## Trip budget

`mna trips edit <trip> --budget '{"amount":4000,"currency":"EUR","appliesTo":"stay"}'`. `appliesTo`
is `stay` or `total`. Only the trip owner can change it, `--budget null` clears it, and it never
appears on share links. Set it only when the owner has stated a budget.

## Location shape — a non-obvious gotcha

Option locations are **written flat and read back nested**. Send `address` / `latitude` /
Expand Down
17 changes: 17 additions & 0 deletions src/commands/options/add.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { colors } from '../../render/colors'
import { reportAndExit, requireApiKey } from '../../util/errors'
import { readJsonObject } from '../../util/json-file'
import { applyFreeCancellation } from './free-cancellation'
import { applyStayFlags } from './stay-details'

const KINDS = ['accommodation', 'transport', 'getting-around'] as const
type Kind = (typeof KINDS)[number]
Expand Down Expand Up @@ -40,13 +41,29 @@ export const optionsAddCommand = defineCommand({
description:
'Accommodation only: free-cancellation deadline (YYYY-MM-DD or ISO date-time). Merged into the body.',
},
details: {
type: 'string',
description:
"Accommodation only: stayDetails as JSON, e.g. '{\"highlight\":\"...\",\"kitchen\":\"private\"}'. Only facts that help choose between this trip's options.",
},
photos: {
type: 'string',
description:
'Accommodation only: photos as a JSON array of { "url", "credit"? }. Only images the owner may use.',
},
website: {
type: 'string',
description:
"Accommodation only: the place's own official website, not a booking site. Photos from it may be linked automatically, credited to the site.",
},
json: { type: 'boolean', default: false, description: 'Output as JSON.' },
},
async run({ args }) {
try {
assertKind(args.kind)
const body = await readJsonObject(args['from-json'])
applyFreeCancellation(body, args['free-cancellation-until'], args.kind)
applyStayFlags(body, { details: args.details, photos: args.photos, website: args.website }, args.kind)

const creds = await loadCredentials()
const apiKey = resolveApiKey(creds)
Expand Down
22 changes: 22 additions & 0 deletions src/commands/options/edit.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,25 @@ describe('options edit — free-cancellation flag', () => {
expect(captured?.body).toEqual({ freeCancellationUntil: '2026-07-02T00:00:00.000Z' })
})
})

describe('options edit — stay details flags', () => {
test('builds the body from --details and --photos alone', async () => {
await run({
tripId: 't',
variantId: 'v',
destinationKey: 'd',
kind: 'accommodation',
optionKey: 'o1',
details: '{"parking":"Garage","noise":null}',
photos: '[{"url":"https://example.com/a.jpg"}]',
json: false,
})

expect(captured?.method).toBe('PATCH')
expect(captured?.url).toContain('/options/accommodation/o1')
expect(captured?.body).toEqual({
stayDetails: { parking: 'Garage', noise: null },
photos: [{ url: 'https://example.com/a.jpg' }],
})
})
})
30 changes: 28 additions & 2 deletions src/commands/options/edit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { colors } from '../../render/colors'
import { reportAndExit, requireApiKey } from '../../util/errors'
import { readJsonObject } from '../../util/json-file'
import { applyFreeCancellation } from './free-cancellation'
import { applyStayFlags } from './stay-details'

const KINDS = ['accommodation', 'transport', 'getting-around'] as const
type Kind = (typeof KINDS)[number]
Expand Down Expand Up @@ -40,17 +41,42 @@ export const optionsEditCommand = defineCommand({
description:
'Accommodation only: free-cancellation deadline (YYYY-MM-DD or ISO date-time). Lets you skip --from-json.',
},
details: {
type: 'string',
description:
"Accommodation only: stayDetails changes as JSON. Only the properties you send change; null clears one, and --details null clears them all. Only facts that help choose between this trip's options.",
},
photos: {
type: 'string',
description:
'Accommodation only: photos as a JSON array of { "url", "credit"? }, replacing the list; null clears it. Only images the owner may use.',
},
website: {
type: 'string',
description:
"Accommodation only: the place's own official website, not a booking site. Photos from it may be linked automatically, credited to the site. null clears it.",
},
json: { type: 'boolean', default: false, description: 'Output as JSON.' },
},
async run({ args }) {
try {
assertKind(args.kind)
if (args['from-json'] === undefined && args['free-cancellation-until'] === undefined) {
throw new Error('Specify --from-json and/or --free-cancellation-until.')
const hasFlag = [
args['from-json'],
args['free-cancellation-until'],
args.details,
args.photos,
args.website,
].some((flag) => flag !== undefined)
if (!hasFlag) {
throw new Error(
'Specify at least one of --from-json, --free-cancellation-until, --details, --photos, --website.',
)
}
const body =
args['from-json'] !== undefined ? await readJsonObject(args['from-json']) : {}
applyFreeCancellation(body, args['free-cancellation-until'], args.kind)
applyStayFlags(body, { details: args.details, photos: args.photos, website: args.website }, args.kind)

const creds = await loadCredentials()
const apiKey = resolveApiKey(creds)
Expand Down
68 changes: 68 additions & 0 deletions src/commands/options/stay-details.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
import { describe, expect, test } from 'bun:test'
import { applyStayFlags } from './stay-details'

describe('applyStayFlags', () => {
test('leaves the body alone without the flags', () => {
const body = { name: 'Villa' }
applyStayFlags(body, {}, 'transport')
expect(body).toEqual({ name: 'Villa' })
})

test('sets and clears the website', () => {
const body: Record<string, unknown> = {}
applyStayFlags(body, { website: 'https://hotel.example/' }, 'accommodation')
expect(body.website).toBe('https://hotel.example/')

applyStayFlags(body, { website: 'null' }, 'accommodation')
expect(body.website).toBeNull()
})

test('refuses a website that is not a web address, and other kinds', () => {
expect(() => applyStayFlags({}, { website: 'javascript:alert(1)' }, 'accommodation')).toThrow('--website')
expect(() => applyStayFlags({}, { website: 'https://hotel.example/' }, 'transport')).toThrow('accommodation')
})

test('sets stayDetails and photos', () => {
const body: Record<string, unknown> = {}
applyStayFlags(
body,
{
details: '{"highlight":"Ski to the door","kitchen":"private"}',
photos: '[{"url":"https://example.com/a.jpg","credit":"Anna"}]',
},
'accommodation',
)
expect(body).toEqual({
stayDetails: { highlight: 'Ski to the door', kitchen: 'private' },
photos: [{ url: 'https://example.com/a.jpg', credit: 'Anna' }],
})
})

test('a flag wins over the same field from the JSON file', () => {
const body: Record<string, unknown> = { stayDetails: { noise: 'Bar nearby' } }
applyStayFlags(body, { details: '{"parking":"Garage"}' }, 'accommodation')
expect(body.stayDetails).toEqual({ parking: 'Garage' })
})

test('passes null through, which clears the field', () => {
const body: Record<string, unknown> = {}
applyStayFlags(body, { details: 'null', photos: 'null' }, 'accommodation')
expect(body).toEqual({ stayDetails: null, photos: null })
})

test.each(['transport', 'getting-around'])('rejects the %s kind', (kind) => {
expect(() => applyStayFlags({}, { details: '{}' }, kind)).toThrow('only valid for the "accommodation" kind')
})

test('rejects malformed details', () => {
expect(() => applyStayFlags({}, { details: '{oops' }, 'accommodation')).toThrow('Invalid JSON in --details')
})

test('rejects details that are not an object', () => {
expect(() => applyStayFlags({}, { details: '["x"]' }, 'accommodation')).toThrow('--details must be a JSON object')
})

test('rejects photos that are not a list', () => {
expect(() => applyStayFlags({}, { photos: '{"url":"x"}' }, 'accommodation')).toThrow('--photos must be a JSON array')
})
})
36 changes: 36 additions & 0 deletions src/commands/options/stay-details.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import { parseJsonFlag, parseJsonObjectFlag } from '../../util/json-flag'

/**
* Merge the `--details`, `--photos` and `--website` flags into an option body. These
* fields exist only on accommodation, so any other kind is rejected. A flag overrides
* the same field in the `--from-json` file.
*/
export function applyStayFlags(
body: Record<string, unknown>,
flags: { details?: string; photos?: string; website?: string },
kind: string,
): void {
if (flags.details === undefined && flags.photos === undefined && flags.website === undefined) return
if (kind !== 'accommodation') {
throw new Error('--details, --photos and --website are only valid for the "accommodation" kind.')
}

if (flags.details !== undefined) {
body.stayDetails = parseJsonObjectFlag(flags.details, '--details')
}
if (flags.photos !== undefined) {
const photos = parseJsonFlag(flags.photos, '--photos')
if (photos !== null && !Array.isArray(photos)) {
throw new Error(
'--photos must be a JSON array of { "url": ..., "credit"?: ... }, or null to clear it.',
)
}
body.photos = photos
}
if (flags.website !== undefined) {
if (flags.website !== 'null' && !/^https?:\/\/\S+$/.test(flags.website)) {
throw new Error('--website must be an http or https URL, or null to clear it.')
}
body.website = flags.website === 'null' ? null : flags.website
}
}
Loading
Loading