From 51dcc81f5dc5e23fa997ddf64c1edcc2973b3918 Mon Sep 17 00:00:00 2001 From: "Paul K." Date: Thu, 19 Nov 2026 19:16:45 -0500 Subject: [PATCH] fix: make the flags and flow features the docs promised actually work (v2.16.0) The docs audit in #242 found commands that ignored their own flags or silently did something risky. Each was reproduced with the real CLI on main and confirmed fixed on this branch. - sync run: honour the profile's memory.embed, then defaults.embedOnSync. --embed was registered with a default of false, so "no flag" always meant "don't embed". The enrich phase now gets --embed/--no-embed too. - mem search --no-track and mem add --no-embed: read the property commander actually sets (track/embed), so both flags work. - mem search --deep: require hybrid search. When it can't run, fail and list what's missing (OpenAI key, pgvector) instead of quietly returning full-text results. - flow execute --mock: mock file-write steps too (report path and bytesWritten, write nothing). - Ctrl+C in flow execute/resume: really pause. The run stops before the next step, is saved as paused, and prints the resume command; a bash or code step the Ctrl+C interrupts re-runs on resume. A second Ctrl+C quits at once and still saves the run as paused. - onError fallback: run the fallbackStepId step when the step fails. The fallback must be a sibling and is skipped in normal order. The validator now checks fallbackStepId and rejects fallback in defaultOnError. - sync init: refuse to overwrite an existing profile unless --force (re-seed) or --config (merge). The drift hint now says --force and warns that it replaces the profile. - one --agent logout: needs --force, and clears only the config in effect unless --scope global|both. Docs (README, skill, flows reference, guide, help text) updated to match. Co-Authored-By: Claude Opus 5.5 --- README.md | 21 +++-- package-lock.json | 4 +- package.json | 2 +- skills/one/SKILL.md | 14 +-- skills/one/references/flows.md | 8 +- src/cli.ts | 12 ++- src/commands/flow.ts | 90 +++++++++++++++--- src/commands/logout.test.ts | 67 +++++++++++++ src/commands/logout.ts | 76 +++++++++++++-- src/commands/mem.ts | 4 +- src/commands/mem/flags.test.ts | 51 ++++++++++ src/commands/mem/records.ts | 51 ++++++++-- src/lib/flow-engine.ts | 125 ++++++++++++++++++++++--- src/lib/flow-fallback.test.ts | 104 ++++++++++++++++++++ src/lib/flow-mock.test.ts | 60 ++++++++++++ src/lib/flow-pause.test.ts | 94 +++++++++++++++++++ src/lib/flow-runner.ts | 44 ++++++--- src/lib/flow-schema.ts | 10 +- src/lib/flow-types.ts | 7 ++ src/lib/flow-validator.ts | 16 ++++ src/lib/guide-content.ts | 22 +++-- src/lib/memory/sync/embed-flag.test.ts | 46 +++++++++ src/lib/memory/sync/enrich.ts | 7 +- src/lib/memory/sync/index.ts | 50 ++++++++-- src/lib/memory/sync/init-guard.test.ts | 70 ++++++++++++++ src/lib/memory/sync/mem-writer.ts | 13 ++- src/lib/memory/sync/profile.ts | 6 ++ src/lib/memory/sync/runner.ts | 1 + 28 files changed, 971 insertions(+), 104 deletions(-) create mode 100644 src/commands/logout.test.ts create mode 100644 src/commands/mem/flags.test.ts create mode 100644 src/lib/flow-fallback.test.ts create mode 100644 src/lib/flow-mock.test.ts create mode 100644 src/lib/flow-pause.test.ts create mode 100644 src/lib/memory/sync/embed-flag.test.ts create mode 100644 src/lib/memory/sync/init-guard.test.ts diff --git a/README.md b/README.md index 5617df6..dcefbb8 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ one login # Opens the browser to sign in and create a key one logout # Clear local credentials ``` -The first `one login` writes the global config; once a key exists it asks whether the new one applies globally or to this directory. For a project key from the start, use `one init -p`. `one logout` asks which config to clear when both a project and a global config exist, and deletes the whole file (API key, OpenAI key, access control and memory settings). The API key itself stays active until you revoke it in the dashboard. +The first `one login` writes the global config; once a key exists it asks whether the new one applies globally or to this directory. For a project key from the start, use `one init -p`. `one logout` asks which config to clear when both a project and a global config exist, and deletes the whole file (API key, OpenAI key, access control and memory settings). With `--agent` there's no prompt: it needs `--force` (without it, it returns `confirmation_required` and the config it would clear), and it clears only the config in effect (the project config if there is one) unless you pass `--scope global` or `--scope both`. The API key itself stays active until you revoke it in the dashboard. The browser consent page names the key and tags it with where this CLI is installed (scope, project path, machine, OS user, CLI version, chosen harnesses, and the per-install device id unless telemetry is off) so you can find and revoke it from Settings → API keys. The terminal prints exactly what will be sent before the browser opens. @@ -422,6 +422,7 @@ One ships a local memory store (a real Postgres process bootstrapped on demand v one mem add note '{"content":"Design review is Thursday"}' --tags work --weight 7 one mem update '{"status":"done"}' # merges into data; refreshes searchable_text one mem search "design review" # FTS; hybrid with an OpenAI key + pgvector +one mem search "design review" --deep # hybrid or an error naming what's missing (no FTS fallback) one mem list note --limit 20 # Merge keys (`keys[]`) are a first-class column (unique across ACTIVE records; @@ -477,7 +478,8 @@ one sync models stripe one sync init stripe balanceTransactions # Optional: declare clean fields for embedding, then preview -# (--config merges into the existing profile; without it, init replaces the profile) +# (--config merges into the existing profile. Without it, init refuses when a +# profile already exists; --force replaces it with the built-in) one sync init stripe balanceTransactions --config '{ "memory": { "embed": true, @@ -487,9 +489,10 @@ one sync init stripe balanceTransactions --config '{ one sync test stripe/balanceTransactions --show-searchable # Run — every row lands in memory (enriching profiles also keep a project-local -# SQLite mirror). --embed embeds the rows; the profile's memory.embed alone is not -# applied today. --since only applies to profiles with a dateFilter (Stripe has none). -one sync run stripe --embed +# SQLite mirror). Rows are embedded when the profile's memory.embed says so (else +# defaults.embedOnSync); --embed / --no-embed override it for one run. +# --since only applies to profiles with a dateFilter (Stripe has none). +one sync run stripe one mem sync run stripe # identical (alias) # Profiles with `enrich` run a second detail pass. It enriches each record ONCE; # the list pass thereafter merges rather than replaces, so the enriched payload @@ -526,7 +529,7 @@ one sync run stripe --full-refresh | `profiles [platform]` | List built-in pre-validated profiles | | `doctor` | Verify sync engine health (exits non-zero when not ready) | | `models ` | Discover available data models | -| `init ` | Create a profile from the built-in or inference (replaces an existing one); `--config` merges into it. Auto-tests | +| `init ` | Create a profile from the built-in or inference. If one exists it refuses unless you pass `--config` (merges into it) or `--force` (replaces it). Auto-tests | | `test /` | Validate profile. `--show-searchable` previews embedded text | | `suggest-searchable /` | Rank candidate `memory.searchable` paths from a live sample | | `approve ` | Approve the shell commands (`transform`, hooks) in profiles you didn't create | @@ -669,13 +672,13 @@ one flow execute welcome-customer -v -i email=jane@example.com Connection inputs with a `connection` field in the workflow definition are auto-resolved when the user has exactly one connection for that platform (top-level runs only, not sub-flows or resumes). -Ctrl+C does not pause a run. A run that fails can be resumed with `one flow resume `. +Press Ctrl+C to pause a run: it stops before the next step and prints the `one flow resume ` command (with the `--allow-*`/`--confirm-write` flags it needs). A bash or code step that the Ctrl+C interrupts runs again on resume. Press Ctrl+C again to quit at once; the run is still saved as paused. A run that fails can also be resumed with `one flow resume `. | Option | What it does | |--------|-------------| | `-i, --input ` | Input parameter (repeatable) | | `--dry-run` | Resolve each step's interpolations and show what they evaluate to, without running actions, code, bash or file steps. Transform and condition expressions are evaluated, in the sandbox. `$.input.*`/`$.env.*` resolve up front; `$.steps.*` refs are reported as deferred (they're produced at runtime). Still needs required inputs and `--allow-bash`/`--allow-code`, and records a run. | -| `--mock` | Mock `action`, `paginate` and `bash` steps (an action returns its schema's example response when it has one). Every other step runs for real, `file-write` included. A mocked step's `response` is `{"_mock": true}`; read `.output`. Works with or without `--dry-run` | +| `--mock` | Mock `action`, `paginate`, `bash` and `file-write` steps (an action returns its schema's example response when it has one; `file-write` steps report `{ path, bytesWritten }` without writing anything). Every other step runs for real, `code.module` included. A mocked step's `response` is `{"_mock": true}`; read `.output`. Works with or without `--dry-run` | | `--stop-after ` | Execute steps up to and including ``, then stop (later steps are not run). Combined with `--dry-run`, runs earlier steps for real and dry-resolves `` against their output without executing it. Use a top-level step or a loop/condition/while child; a `parallel` substep is ignored. Inspect what ran with `one flow inspect `. | | `--skip-validation` | Skip input validation against action schemas | | `--allow-bash` | Allow bash step execution (disabled by default for security) | @@ -706,7 +709,7 @@ one flow validate welcome-customer ### `one flow resume ` -Resume a failed workflow run. It skips the top-level steps that completed and re-runs the failed step from its start (a failed loop, parallel, while or sub-flow step re-runs all its inner steps, so writes there can repeat). It uses the current flow file. +Resume a failed or paused workflow run. It skips the top-level steps that completed and re-runs the failed step from its start (a failed loop, parallel, while or sub-flow step re-runs all its inner steps, so writes there can repeat). It uses the current flow file. ```bash one flow resume abc123 diff --git a/package-lock.json b/package-lock.json index 89caa2f..6b93ed2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@withone/cli", - "version": "2.15.2", + "version": "2.16.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@withone/cli", - "version": "2.15.2", + "version": "2.16.0", "dependencies": { "@clack/prompts": "^0.9.1", "commander": "^13.1.0", diff --git a/package.json b/package.json index 7467fc5..d3f0c69 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@withone/cli", - "version": "2.15.2", + "version": "2.16.0", "description": "CLI for managing One", "type": "module", "files": [ diff --git a/skills/one/SKILL.md b/skills/one/SKILL.md index a5eaa28..0c451ca 100644 --- a/skills/one/SKILL.md +++ b/skills/one/SKILL.md @@ -31,7 +31,7 @@ one login # Browser-based login (opens app.withone.ai) one logout # Clear local credentials ``` -`one login` opens the browser for OAuth authentication and automatically creates and stores an API key. If already logged in, the user can choose to log in globally or for the current directory. It is not available with `--agent`; use `one --agent init --auth browser [-p]` instead. `one logout` shows current session info and confirms before clearing credentials, but **with `--agent` there is no confirmation**: it deletes both this directory's project config and the global config. Never run it unless the user asked to log out. +`one login` opens the browser for OAuth authentication and automatically creates and stores an API key. If already logged in, the user can choose to log in globally or for the current directory. It is not available with `--agent`; use `one --agent init --auth browser [-p]` instead. `one logout` shows current session info and confirms before clearing credentials, With `--agent` there's no prompt: without `--force` it returns `confirmation_required` and the config it would clear. With `--force` it clears only the config in effect (the project config if there is one, else the global one); `--scope global|both` picks another. Never run it unless the user asked to log out. The consent page asks which harness will use the key (Claude Code, Codex, Cursor, …) and records the install location as tags on the key (`scope:global` / `scope:project`, `path:`, `host:`, `user:`, `harness:`, and `device:` unless telemetry is off). The CLI prints what it will send before opening the browser. `one whoami` shows the key's name once it is stored. @@ -227,6 +227,7 @@ Underneath, the store has no `platform` column — `type` is the only platform-s one --agent mem add note '{"content":"..."}' --tags work --weight 7 one --agent mem update '{"status":"done"}' # merges into data; refreshes searchable_text one --agent mem search "deadline" # hybrid with key + pgvector, else FTS +one --agent mem search "deadline" --deep # hybrid, or an error listing what's missing (no FTS fallback) one --agent mem list note --limit 20 one --agent mem link relates_to --bi @@ -298,8 +299,8 @@ export OPENAI_API_KEY=sk-... # Check built-in profiles (pre-validated configs for common platforms) one --agent sync profiles -# Setup — seeds from the built-in. Without --config it REPLACES an existing profile; -# with --config it merges into the existing one. +# Setup — seeds from the built-in. If a profile already exists, init refuses +# (status: "exists"); --config merges into it, --force replaces it. one --agent sync init stripe balanceTransactions # If _complete: true and _test.ok: true → ready to run @@ -327,8 +328,9 @@ one --agent sync test attio/attioPeople --show-searchable # Iterate until the numbers match intent. # Run — memory is always written; pass --no-memory to skip (rare). -# Add --embed to embed: the profile's memory.embed alone isn't applied today. -one --agent sync run stripe --embed +# Embeds when the profile's memory.embed says so (else defaults.embedOnSync); +# --embed / --no-embed override it for one run. +one --agent sync run stripe one --agent sync schema stripe/customers # inspect field paths/types before querying one --agent sync query stripe/balanceTransactions --where "status=available" --limit 20 one --agent sync search "refund" # this project's synced models (mem search works anywhere) @@ -356,7 +358,7 @@ Without declared paths, the default walker concatenates every string in the reco **Extracting a flat field? Use `derive`, not `transform`.** `derive` computes top-level fields from paths already in the record (`"derive": { "from_email": { "path": "messages[0].payload.headers[name=From].value", "extract": "email" } }`), using the same path syntax as `identityKeys`. `transform` spawns `sh -c`, so it needs `jq` on PATH and silently does nothing on Windows — never put one in a profile you intend to share. Shell commands in a profile you didn't create with `sync init --config` (e.g. one from a cloned repo) are refused until approved: `one --agent sync approve ` returns the commands; show them to the user and re-run with `--yes` only if they agree. A path that resolves to nothing omits the field rather than writing null. -**Installed profiles do not auto-update.** `sync run` reads only `.one/sync/profiles/_.json` and never merges the shipped built-in, so a profile created before a capability shipped silently lacks it — a pre-#167 gmail profile writes zero identity keys, forever, with no change in record counts. `sync run` warns when the built-in declares `identityKeys` / `identityKey` / `enrich` / `dateFilter` / `memory` that your copy lacks (agent mode: a `profileDrift` array). **Don't fix it with a bare `one sync init `**: without `--config` that replaces the profile and loses the user's `connection.tag`, `memory`, hooks and other edits. Copy just the missing fields from `one --agent sync profiles ` and pass them with `one sync init --config '{...}'`, which merges. +**Installed profiles do not auto-update.** `sync run` reads only `.one/sync/profiles/_.json` and never merges the shipped built-in, so a profile created before a capability shipped silently lacks it — a pre-#167 gmail profile writes zero identity keys, forever, with no change in record counts. `sync run` warns when the built-in declares `identityKeys` / `identityKey` / `enrich` / `dateFilter` / `memory` that your copy lacks (agent mode: a `profileDrift` array). **Don't fix it with `one sync init --force`** (the hint's suggestion): that replaces the profile and loses the user's `connection.tag`, `memory`, hooks and other edits. A bare `sync init` refuses because the profile exists. Copy just the missing fields from `one --agent sync profiles ` and pass them with `one sync init --config '{...}'`, which merges. **Old project sync data is never imported automatically.** `sync run` ignores `.one/sync/data/*.db` and `.one/sync/state/` (a cloned repo can ship them) and prints a hint. Show the user `one --agent mem migrate --dry-run` before running `mem migrate`. diff --git a/skills/one/references/flows.md b/skills/one/references/flows.md index 7f13867..ddb3dc9 100644 --- a/skills/one/references/flows.md +++ b/skills/one/references/flows.md @@ -636,7 +636,7 @@ Strategies: `fail` (default), `continue`, `retry`, `fallback`. - `continue` records the step as failed (`status`, `error`, `errorCode`) and moves on. - `retry` retries; if it still fails (or `failFastOn` matches, or `retryOn` doesn't), the step fails the flow. -- `fallback` with `fallbackStepId` records the failure and moves on, exactly like `continue`: the engine does **not** run the named step. Without `fallbackStepId` it behaves like `fail`. To run a recovery step, gate it with `"if": "$.steps..status === 'failed'"`. +- `fallback` with `fallbackStepId` runs the named step when this one fails. The fallback step must be in the same steps list; it is skipped in normal order and runs only as a fallback. The failed step stays recorded (`status: "failed"`, `fallback: ""`), and the fallback's result is at `$.steps.`. If the fallback fails too, the flow fails. A fallback can't have a fallback of its own, and `fallback` isn't allowed in `defaultOnError`. The validator requires `fallbackStepId`. **Flow-level default (cli#93).** Set `defaultOnError` at the top of the flow and every step without its own `onError` inherits it — handy when most steps should `continue` (e.g. rendering/formatting pipelines) and you don't want to repeat it N times. A step opts out by declaring its own `onError`: @@ -759,11 +759,11 @@ Three tools that turn "re-run the whole 40-step flow to debug step 30" into near - **`--dry-run`** — resolves every step's interpolations and shows what they evaluate to, *without executing any step*. `$.input.*` / `$.env.*` resolve immediately; `$.steps.*` references are reported as `deferred` (they're produced at runtime). Transform/condition/while steps show their *evaluated* result; if a transform can't evaluate yet because it reads a step that hasn't run, it's marked `deferred` (depends on a later step) rather than shown as an error — genuine problems (syntax errors, missing inputs, a missing field on a step that *did* run) still surface as errors. Catches wiring bugs (typo'd input names, wrong field paths) with zero API spend. In `--agent` mode this is the `flow:dry-run` event whose `steps[]` carry a `references` table (`{selector, value, status}` where status is `resolved` | `deferred` | `missing`), an evaluated `resolved` value, and a `deferred` / `error` flag for expression steps. - **`--stop-after `** — executes steps up to and including ``, then stops; later steps don't run. Isolates where a long flow breaks. Emits a `flow:stopped` event; the run's partial state is saved. Target a top-level step or a loop/condition/while child: a `parallel` substep is accepted but ignored (every step then runs for real, even with `--dry-run`), and a target inside a loop stops after the loop's first iteration. -- **`--mock`** — runs the flow with `action`, `paginate` and `bash` steps mocked: an action's `output` is its example response when it has one, otherwise the resolved config; paginate and bash echo their config. A mocked step's `response` is `{"_mock": true}`, so read mocked data from `.output`. **Every other step runs for real, including `file-write`.** Works with or without `--dry-run`. +- **`--mock`** — runs the flow with `action`, `paginate`, `bash` and `file-write` steps mocked: an action's `output` is its example response when it has one, otherwise the resolved config; paginate and bash echo their config; `file-write` steps report `{ path, bytesWritten }` without writing anything. A mocked step's `response` is `{"_mock": true}`, so read mocked data from `.output`. **Every other step runs for real, including `code.module`.** Works with or without `--dry-run`. - **`--dry-run --stop-after `** — runs the steps *before* `` for real, then dry-resolves `` against that **real** accumulated context (so its `$.steps.*` references resolve to actual upstream output) and stops without executing it. The honest way to preview "what will step N actually receive". Emits a `step:dry-resolve` event for the target. - **`flow inspect `** — prints a past run's per-step status, durations, errors, and outputs from its persisted state file (post-mortem, no re-run). Use after `--stop-after`, or on any failed run, to see exactly what each step produced. `--full` disables output truncation. -Ctrl+C does not pause a run; let it finish or fail, then use `flow resume` on a failed run. +Press Ctrl+C to pause a run: it stops before the next step and prints the `one flow resume ` command (with the `--allow-*`/`--confirm-write` flags it needs). A bash or code step that the Ctrl+C interrupts runs again on resume. Press Ctrl+C again to quit at once; the run is still saved as paused. With `--agent` a paused run returns `{"status": "paused", "pausedBefore", "resume"}` and exits 130. ## Important Notes @@ -775,6 +775,6 @@ Ctrl+C does not pause a run; let it finish or fail, then use `flow resume` on a - In agent mode, flows with write steps require `--confirm-write` - `code.module` steps require `--allow-code` flag (they run with full Node access) - Action steps validate required params before executing — pass `--skip-validation` to bypass -- `--mock` mocks only action, paginate and bash steps (actions return their schema's example output when it has one); other steps, file writes included, run for real +- `--mock` mocks action, paginate, bash and file-write steps (actions return their schema's example output when it has one; file writes touch nothing); other steps, `code.module` included, run for real - State is persisted after every step; resume skips completed top-level steps and re-runs the failed one from its start - For bash+Claude steps, always set timeout to 180000+ and run sequentially (not in parallel) diff --git a/src/cli.ts b/src/cli.ts index d20378f..10ce722 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -111,7 +111,7 @@ program Memory (unified store; auto-inits on first use — "one guide memory" for full reference): one mem add Add a record (--tags, --keys, --weight, --embed) - one mem search "" Full-text search; hybrid with an OpenAI key + pgvector + one mem search "" Full-text search; hybrid with an OpenAI key + pgvector (--deep: hybrid or fail) one mem list List records of a type one mem link Create a typed graph edge (--bi for bidirectional) one mem find-by-key Every record tied to a key (e.g. email:jane@acme.com), by type @@ -120,7 +120,7 @@ program Data Sync (writes into memory; "one guide sync" for the full reference): one sync models Discover available data models - one sync init Create a profile from the built-in (--config merges into an existing one) + one sync init Create a profile from the built-in (--config merges, --force replaces) one sync test / Validate profile. --show-searchable previews embedded text one sync run Sync data (--embed, --full-refresh, --since, --no-memory) one sync query / Query memory (--where supports dotted paths) @@ -245,8 +245,10 @@ program program .command('logout') .description('Clear local credentials') - .action(async () => { - await logoutCommand(); + .option('-f, --force', 'Agent mode: required to clear credentials (no prompt)') + .option('--scope ', 'Agent mode: project, global or both (default: the config in effect)') + .action(async (options: { force?: boolean; scope?: string }) => { + await logoutCommand(options); }); const skills = program @@ -613,7 +615,7 @@ flow .description('Execute a workflow by key or file path') .option('-i, --input ', 'Input parameter (repeatable)', collect, []) .option('--dry-run', 'Resolve each step\'s interpolations and show what they evaluate to, without running actions, code, bash or file steps. Transform and condition expressions are evaluated in the sandbox ($.steps.* refs resolve at runtime)') - .option('--mock', 'Mock action, paginate and bash steps (actions return their example response); other steps, file-write included, run for real') + .option('--mock', 'Mock action, paginate, bash and file-write steps (actions return their example response; file writes touch nothing); other steps, code.module included, run for real') .option('--stop-after ', 'Execute steps up to and including , then stop (later steps are not run). With --dry-run, runs earlier steps for real and dry-resolves against their output without executing it. See: one flow inspect') .option('--skip-validation', 'Skip input validation against action schemas') .option('--allow-bash', 'Allow bash step execution (disabled by default for security)') diff --git a/src/commands/flow.ts b/src/commands/flow.ts index efe6aaa..973921b 100644 --- a/src/commands/flow.ts +++ b/src/commands/flow.ts @@ -7,7 +7,7 @@ import { validateFlow } from '../lib/flow-validator.js'; import { FlowRunner, loadFlowWithMeta, listFlows, saveFlow, resolveFlowPath, flowRequiresBash, flowUsesCodeModules, walkSteps, flowWritesOf } from '../lib/flow-runner.js'; import { resolveActionDetails } from '../lib/action-details.js'; import { WRITE_CONFIRMATION_HINT } from '../lib/access-gate.js'; -import type { DryResolvedStep, DryResolvedRef } from '../lib/flow-engine.js'; +import { FlowPauseSignal, type DryResolvedStep, type DryResolvedRef } from '../lib/flow-engine.js'; import type { Flow, FlowEvent, StepResult } from '../lib/flow-types.js'; import type { PermissionLevel } from '../lib/types.js'; import fs from 'node:fs'; @@ -271,6 +271,66 @@ async function confirmFlowWrites( process.exit(1); } +/** The `flow resume` command for a run, with the permission flags it was started with. */ +function resumeCommandFor(runId: string, options: { allowBash?: boolean; allowCode?: boolean; confirmWrite?: boolean }): string { + const flags = [ + options.allowBash ? '--allow-bash' : '', + options.allowCode ? '--allow-code' : '', + options.confirmWrite ? '--confirm-write' : '', + ].filter(Boolean); + return [`one${output.isAgentMode() ? ' --agent' : ''} flow resume ${runId}`, ...flags].join(' '); +} + +/** + * Ctrl+C while a flow runs: the first press pauses before the next step; the + * second quits at once. Either way the run is saved as paused for + * `flow resume`. Returns the function that removes the handler. + */ +function installPauseHandler(runner: FlowRunner, resumeCommand: string): () => void { + let presses = 0; + const handler = (): void => { + presses++; + if (presses === 1) { + runner.requestPause(); + if (!output.isAgentMode()) { + console.log(`\n${pc.yellow('Pausing before the next step...')} ${pc.dim('(Ctrl+C again to quit now)')}`); + } + return; + } + runner.markInterrupted(); + if (output.isAgentMode()) { + output.json({ event: 'workflow:result', runId: runner.getRunId(), status: 'paused', interrupted: true, resume: resumeCommand }); + } else { + console.log(`\n${pc.yellow('Stopped.')} Resume with: ${pc.cyan(resumeCommand)}`); + } + process.exit(130); + }; + process.on('SIGINT', handler); + return () => process.off('SIGINT', handler); +} + +/** Report a run that stopped on Ctrl+C, then exit 130 (interrupted). */ +function reportPaused(runner: FlowRunner, error: FlowPauseSignal, resumeCommand: string): never { + const completed = FlowRunner.loadRunState(runner.getRunId())?.completedSteps.length ?? 0; + if (output.isAgentMode()) { + output.json({ + event: 'workflow:result', + runId: runner.getRunId(), + logFile: runner.getLogPath(), + statePath: runner.getStatePath(), + status: 'paused', + pausedBefore: error.stepId, + resume: resumeCommand, + }); + } else { + output.note( + `Paused before step "${error.stepId}" (${completed} step${completed === 1 ? '' : 's'} done).\nResume with: ${pc.cyan(resumeCommand)}`, + 'Paused', + ); + } + process.exit(130); +} + export async function flowExecuteCommand( keyOrPath: string, options: { input?: string[]; dryRun?: boolean; verbose?: boolean; mock?: boolean; allowBash?: boolean; allowCode?: boolean; skipValidation?: boolean; outputFile?: string; stopAfter?: string; confirmWrite?: boolean }, @@ -364,14 +424,9 @@ export async function flowExecuteCommand( const logPath = runner.getLogPath(); const runId = runner.getRunId(); - // Set up SIGINT handler for pause - const sigintHandler = () => { - runner.requestPause(); - if (!output.isAgentMode()) { - console.log(`\n${pc.yellow('Pausing after current step completes...')} (run ID: ${runId})`); - } - }; - process.on('SIGINT', sigintHandler); + // Ctrl+C pauses before the next step; a second Ctrl+C quits now. + const resumeCommand = resumeCommandFor(runId, options); + const removePauseHandler = installPauseHandler(runner, resumeCommand); // Debug-mode captures (#97): the engine streams these as events; we hold the // last-seen payloads to render a focused summary after execution returns. @@ -421,7 +476,7 @@ export async function flowExecuteCommand( onEvent, }); - process.off('SIGINT', sigintHandler); + removePauseHandler(); if (!options.verbose && !output.isAgentMode()) { execSpinner.stop(stoppedAfter ? 'Workflow stopped' : dryRunSteps ? 'Dry run complete' : 'Workflow completed'); @@ -496,7 +551,11 @@ export async function flowExecuteCommand( output.note('Dry run — no steps were executed', 'Dry Run'); } } catch (error) { - process.off('SIGINT', sigintHandler); + removePauseHandler(); + if (error instanceof FlowPauseSignal) { + if (!options.verbose && !output.isAgentMode()) execSpinner.stop('Workflow paused'); + reportPaused(runner, error, resumeCommand); + } if (!options.verbose && !output.isAgentMode()) { execSpinner.stop('Workflow failed'); } @@ -676,6 +735,9 @@ export async function flowResumeCommand( const spinner = output.createSpinner(); spinner.start(`Resuming run ${runId} (${state!.completedSteps.length} steps already completed)...`); + const resumeCommand = resumeCommandFor(runId, options); + const removePauseHandler = installPauseHandler(runner, resumeCommand); + try { const context = await runner.resume(flow, api, permissions, actionIds, { onEvent, @@ -683,6 +745,7 @@ export async function flowResumeCommand( allowBash: options.allowBash, allowCode: options.allowCode, }); + removePauseHandler(); spinner.stop('Workflow completed'); if (output.isAgentMode()) { @@ -699,6 +762,11 @@ export async function flowResumeCommand( console.log(` ${pc.green('✓')} Resumed and completed successfully`); console.log(` ${pc.dim(`Log: ${runner.getLogPath()}`)}`); } catch (error) { + removePauseHandler(); + if (error instanceof FlowPauseSignal) { + spinner.stop('Workflow paused'); + reportPaused(runner, error, resumeCommand); + } spinner.stop('Resume failed'); const errorMsg = error instanceof Error ? error.message : String(error); diff --git a/src/commands/logout.test.ts b/src/commands/logout.test.ts new file mode 100644 index 0000000..861b16d --- /dev/null +++ b/src/commands/logout.test.ts @@ -0,0 +1,67 @@ +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import type { Command } from 'commander'; + +import { program } from '../cli.js'; +import { resolveLogoutTargets } from './logout.js'; + +// `one --agent logout` deleted the project AND the global config with no +// confirmation. Agent mode now needs --force, and clears only the config in +// effect (project if there is one, else global) unless --scope says otherwise. + +function sub(parent: Command, name: string): Command { + const found = parent.commands.find(c => c.name() === name); + assert.ok(found, `expected a "${name}" command`); + return found; +} + +const P = '/home/u/.one/projects/app/config.json'; +const G = '/home/u/.one/config.json'; + +describe('logout flags', () => { + it('registers --force and --scope', () => { + const logout = sub(program, 'logout'); + assert.ok(logout.options.find(o => o.long === '--force')); + assert.ok(logout.options.find(o => o.long === '--scope')); + }); +}); + +describe('resolveLogoutTargets', () => { + it('defaults to the project config when there is one', () => { + assert.deepEqual(resolveLogoutTargets({ projectPath: P, globalPath: G }), { + targets: [{ scope: 'project', path: P }], + }); + }); + + it('falls back to the global config', () => { + assert.deepEqual(resolveLogoutTargets({ projectPath: null, globalPath: G }), { + targets: [{ scope: 'global', path: G }], + }); + }); + + it('clears both only with --scope both', () => { + assert.deepEqual(resolveLogoutTargets({ scope: 'both', projectPath: P, globalPath: G }), { + targets: [{ scope: 'project', path: P }, { scope: 'global', path: G }], + }); + }); + + it('honours an explicit --scope global even when a project config exists', () => { + assert.deepEqual(resolveLogoutTargets({ scope: 'global', projectPath: P, globalPath: G }), { + targets: [{ scope: 'global', path: G }], + }); + }); + + it('errors when the requested scope has no config file', () => { + const r = resolveLogoutTargets({ scope: 'project', projectPath: null, globalPath: G }); + assert.ok('error' in r); + }); + + it('errors on an unknown scope', () => { + const r = resolveLogoutTargets({ scope: 'everything', projectPath: P, globalPath: G }); + assert.ok('error' in r); + }); + + it('returns no targets when there is no config file at all', () => { + assert.deepEqual(resolveLogoutTargets({ projectPath: null, globalPath: null }), { targets: [] }); + }); +}); diff --git a/src/commands/logout.ts b/src/commands/logout.ts index b7c8859..b31e738 100644 --- a/src/commands/logout.ts +++ b/src/commands/logout.ts @@ -35,7 +35,41 @@ function formatWhoami(config: Config, apiKey: string, pc: typeof import('picocol return lines; } -export async function logoutCommand(): Promise { +type ConfigScope = 'project' | 'global'; +export type LogoutScope = ConfigScope | 'both'; +const LOGOUT_SCOPES: readonly LogoutScope[] = ['project', 'global', 'both']; + +/** + * Which config files a logout clears. With no `--scope`, only the config in + * effect: the project config when there is one (it wins resolution), else the + * global one. `both` is opt-in. Paths are null when that file doesn't exist. + */ +export function resolveLogoutTargets(opts: { + scope?: string; + projectPath: string | null; + globalPath: string | null; +}): { targets: Array<{ scope: ConfigScope; path: string }> } | { error: string } { + const { scope, projectPath, globalPath } = opts; + if (scope !== undefined && !LOGOUT_SCOPES.includes(scope as LogoutScope)) { + return { error: `Unknown --scope "${scope}". Use project, global or both.` }; + } + const project = projectPath ? [{ scope: 'project' as const, path: projectPath }] : []; + const global = globalPath ? [{ scope: 'global' as const, path: globalPath }] : []; + if (scope === 'both') return { targets: [...project, ...global] }; + if (scope === 'project' || scope === 'global') { + const found = scope === 'project' ? project : global; + if (found.length === 0) return { error: `There is no ${scope} config to clear.` }; + return { targets: found }; + } + return { targets: project.length > 0 ? project : global }; +} + +const LOGOUT_CONFIRMATION_HINT = + 'Re-run with --force to clear these credentials. This deletes the whole config file, ' + + 'including the OpenAI key, access control and memory settings. ' + + 'Pass --scope project|global|both to choose which config.'; + +export async function logoutCommand(options: { force?: boolean; scope?: string } = {}): Promise { const apiKey = getApiKey(); if (!apiKey) { @@ -48,13 +82,41 @@ export async function logoutCommand(): Promise { } if (output.isAgentMode()) { - // Agent mode: clear resolved config, no prompts - const globalPath = getGlobalConfigPath(); + // Agent mode: no prompts, so deleting needs --force (as `connection delete` + // does), and only the config in effect is cleared unless --scope says so. const projectPath = getProjectConfigPath(); - let cleared = false; - if (fs.existsSync(projectPath)) { fs.unlinkSync(projectPath); cleared = true; } - if (fs.existsSync(globalPath)) { fs.unlinkSync(globalPath); cleared = true; } - output.json({ status: cleared ? 'logged_out' : 'not_logged_in', message: cleared ? 'Credentials cleared.' : 'No config found.' }); + const globalPath = getGlobalConfigPath(); + const plan = resolveLogoutTargets({ + scope: options.scope, + projectPath: fs.existsSync(projectPath) ? projectPath : null, + globalPath: fs.existsSync(globalPath) ? globalPath : null, + }); + if ('error' in plan) { + output.json({ error: plan.error }); + process.exit(1); + } + if (plan.targets.length === 0) { + output.json({ + status: 'not_logged_in', + message: 'No config file found. The key comes from ONE_SECRET or .onerc; remove it there.', + }); + return; + } + if (!options.force) { + output.json({ + status: 'confirmation_required', + error: 'Logging out needs --force in agent mode.', + wouldClear: plan.targets, + _hint: LOGOUT_CONFIRMATION_HINT, + }); + process.exit(1); + } + for (const t of plan.targets) fs.unlinkSync(t.path); + output.json({ + status: 'logged_out', + cleared: plan.targets, + message: 'Credentials cleared. The API key itself stays active; revoke it in the dashboard.', + }); return; } diff --git a/src/commands/mem.ts b/src/commands/mem.ts index 43722e0..61c3034 100644 --- a/src/commands/mem.ts +++ b/src/commands/mem.ts @@ -168,8 +168,8 @@ export function registerMemoryCommands(program: Command): void { .description('Hybrid search across memory (FTS + optional semantic)') .option('--type ', 'Restrict to one record type') .option('--limit ', 'Max results (default 10)') - .option('--deep', 'Force semantic embedding on the query', false) - .option('--no-track', 'Do not bump access_count on results', false) + .option('--deep', 'Require semantic (hybrid) search: fail instead of falling back to full-text when it can\'t run', false) + .option('--no-track', 'Do not bump access_count on results') .option('--include-archived', 'Include archived records', false) .action(memSearchCommand); diff --git a/src/commands/mem/flags.test.ts b/src/commands/mem/flags.test.ts new file mode 100644 index 0000000..0ed1443 --- /dev/null +++ b/src/commands/mem/flags.test.ts @@ -0,0 +1,51 @@ +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import type { Command } from 'commander'; + +import { program } from '../../cli.js'; +import { addEmbedOption, shouldTrackSearchAccess } from './records.js'; + +// Commander turns `--no-track` into `track: false` and `--no-embed` into +// `embed: false`. The handlers read `noTrack` / `noEmbed`, which commander +// never sets, so both flags did nothing: searches always bumped access +// counts, and `mem add --no-embed` still embedded under `embedOnAdd`. + +function sub(parent: Command, name: string): Command { + const found = parent.commands.find(c => c.name() === name); + assert.ok(found, `expected a "${name}" command`); + return found; +} + +const mem = sub(program, 'mem'); + +function parse(cmdName: string, argv: string[]): Record { + const cmd = sub(mem, cmdName); + // Reset option values from any earlier parse, then parse flags only. + for (const o of cmd.options) cmd.setOptionValue(o.attributeName(), o.defaultValue); + cmd.parseOptions(argv); + return cmd.opts(); +} + +describe('mem search --no-track', () => { + it('tracks access by default when the config says so', () => { + assert.equal(shouldTrackSearchAccess(parse('search', []), true), true); + }); + it('does not track when --no-track is passed', () => { + assert.equal(shouldTrackSearchAccess(parse('search', ['--no-track']), true), false); + }); + it('never tracks when the config default is off', () => { + assert.equal(shouldTrackSearchAccess(parse('search', []), false), false); + }); +}); + +describe('mem add --embed / --no-embed', () => { + it('defers to defaults.embedOnAdd with no flag', () => { + assert.deepEqual(addEmbedOption(parse('add', [])), {}); + }); + it('forces embedding with --embed', () => { + assert.deepEqual(addEmbedOption(parse('add', ['--embed'])), { embed: true }); + }); + it('skips embedding with --no-embed', () => { + assert.deepEqual(addEmbedOption(parse('add', ['--no-embed'])), { embed: false }); + }); +}); diff --git a/src/commands/mem/records.ts b/src/commands/mem/records.ts index 31a2704..c8cfe2c 100644 --- a/src/commands/mem/records.ts +++ b/src/commands/mem/records.ts @@ -17,7 +17,14 @@ interface AddFlags { keys?: string; weight?: string; embed?: boolean; - noEmbed?: boolean; +} + +/** + * `--embed` / `--no-embed` both land on `flags.embed` (commander maps + * `--no-embed` to `embed: false`). Unset defers to `defaults.embedOnAdd`. + */ +export function addEmbedOption(flags: { embed?: boolean }): { embed?: boolean } { + return typeof flags.embed === 'boolean' ? { embed: flags.embed } : {}; } export async function memAddCommand(type: string, dataRaw: string, flags: AddFlags): Promise { @@ -27,7 +34,7 @@ export async function memAddCommand(type: string, dataRaw: string, flags: AddFla if (weight !== undefined && (weight < 1 || weight > 10)) { output.error('weight must be between 1 and 10'); } - const opts = flags.noEmbed ? { embed: false } : flags.embed ? { embed: true } : {}; + const opts = addEmbedOption(flags); const record = await addRecord( { type, data, tags: parseCsv(flags.tags), keys: parseCsv(flags.keys), weight }, opts, @@ -206,28 +213,58 @@ interface SearchFlags { type?: string; limit?: string; deep?: boolean; - noTrack?: boolean; + /** `--no-track` sets this to false (commander's negated-flag convention). */ + track?: boolean; includeArchived?: boolean; } +/** `mem search --deep` when semantic search can't run: fail loudly, never fall back to FTS. */ +function deepSearchUnavailable(how: string[]): never { + const message = "Semantic search isn't available, so --deep can't run."; + if (output.isAgentMode()) { + output.json({ error: message, searchMode: 'unavailable', how }); + process.exit(1); + } + output.error([message, ...how.map(h => `- ${h}`)].join('\n')); +} + +/** Bump access counts on results unless `--no-track` or the config turns it off. */ +export function shouldTrackSearchAccess(flags: { track?: boolean }, configDefault: boolean): boolean { + return flags.track !== false && configDefault; +} + export async function memSearchCommand(query: string, flags: SearchFlags): Promise { requireMemoryInit(); const backend = await getBackend(); const cfg = getMemoryConfigOrDefault(); - // `--deep` forces semantic embedding if provider configured. Default also - // does semantic when provider is openai; FTS-only when provider is none. + // Hybrid (FTS + semantic) when an OpenAI key, the provider and pgvector are + // all in place; FTS-only otherwise. `--deep` means "semantic or nothing": + // instead of quietly falling back to FTS it fails and names what's missing. + const vectorSearch = backend.capabilities().vectorSearch; + if (flags.deep) { + // Name every missing piece at once, not one per attempt. + const missing = [ + ...(vectorSearch ? [] : [semanticSearchUpgradeHint({ vectorSearchAvailable: false })!.how]), + ...[semanticSearchUpgradeHint({ vectorSearchAvailable: true })?.how].filter((h): h is string => !!h), + ]; + if (missing.length > 0) deepSearchUnavailable(missing); + } + let queryEmbedding: number[] | null = null; - if ((flags.deep || cfg.embedding.provider === 'openai') && backend.capabilities().vectorSearch) { + if (cfg.embedding.provider === 'openai' && vectorSearch) { const embedded = await embed(query); if (embedded) queryEmbedding = embedded.vector; } + if (flags.deep && !queryEmbedding) { + deepSearchUnavailable(['Embedding the query failed (the OpenAI request returned no vector). Retry, or search without --deep.']); + } const results = await backend.search(query, { type: flags.type, limit: flags.limit ? parsePositiveInt(flags.limit, 10, 'limit') : undefined, queryEmbedding, - trackAccess: !flags.noTrack && cfg.defaults.trackAccessOnSearch, + trackAccess: shouldTrackSearchAccess(flags, cfg.defaults.trackAccessOnSearch), includeArchived: flags.includeArchived, }); diff --git a/src/lib/flow-engine.ts b/src/lib/flow-engine.ts index e2aad41..511ef5d 100644 --- a/src/lib/flow-engine.ts +++ b/src/lib/flow-engine.ts @@ -431,6 +431,29 @@ export class FlowStopSignal extends Error { } } +/** + * Raised when a pause was requested (Ctrl+C): the run stops before `stepId`, + * which hasn't completed and runs again on `flow resume`. Like FlowStopSignal + * it is control flow, never a step failure: no retry, no onError routing. + */ +export class FlowPauseSignal extends Error { + constructor(public readonly stepId: string) { + super(`Flow paused before step "${stepId}" completed`); + this.name = 'FlowPauseSignal'; + } +} + +/** Ids of steps in `steps` that a sibling names as its `onError.fallbackStepId`. */ +function fallbackTargetIds(steps: FlowStep[]): Set { + const ids = new Set(); + for (const s of steps) { + if (s.onError?.strategy === 'fallback' && s.onError.fallbackStepId && s.onError.fallbackStepId !== s.id) { + ids.add(s.onError.fallbackStepId); + } + } + return ids; +} + export type DryRefStatus = 'resolved' | 'deferred' | 'missing'; export interface DryResolvedRef { @@ -1102,14 +1125,16 @@ async function executeParallelStep( ): Promise { const parallel = step.parallel!; const maxConcurrency = parallel.maxConcurrency || 5; - const steps = parallel.steps; + // Fallback targets run only when the sibling that names them fails. + const fallbackTargets = fallbackTargetIds(parallel.steps); + const steps = parallel.steps.filter(s => !fallbackTargets.has(s.id)); const results: StepResult[] = []; // Process in batches of maxConcurrency for (let i = 0; i < steps.length; i += maxConcurrency) { const batch = steps.slice(i, i + maxConcurrency); const batchResults = await Promise.all( - batch.map(s => executeSingleStep(s, context, api, permissions, allowedActionIds, options, flowStack)) + batch.map(s => executeSingleStep(s, context, api, permissions, allowedActionIds, options, flowStack, parallel.steps)) ); // Feature 1: Explicit keying of parallel substep outputs by ID for (let j = 0; j < batch.length; j++) { @@ -1135,11 +1160,22 @@ function executeFileReadStep(step: FlowStep, context: FlowContext): StepResult { return { status: 'success', output, response: output }; } -function executeFileWriteStep(step: FlowStep, context: FlowContext): StepResult { +function executeFileWriteStep(step: FlowStep, context: FlowContext, opts: { mock?: boolean } = {}): StepResult { const config = step.fileWrite!; const filePath = resolveValue(config.path, context) as string; const content = resolveValue(config.content, context); const resolvedPath = path.resolve(filePath); + const stringContent = typeof content === 'string' ? content : JSON.stringify(content, null, 2); + + // `--mock`: report what would be written, in the real output shape, and + // leave the filesystem alone (no file, no parent directories). + if (opts.mock) { + return { + status: 'success', + output: { path: resolvedPath, bytesWritten: stringContent.length, _mock: true }, + response: { _mock: true, path: resolvedPath }, + }; + } // Ensure parent directory exists const dir = path.dirname(resolvedPath); @@ -1147,8 +1183,6 @@ function executeFileWriteStep(step: FlowStep, context: FlowContext): StepResult fs.mkdirSync(dir, { recursive: true }); } - const stringContent = typeof content === 'string' ? content : JSON.stringify(content, null, 2); - if (config.append) { fs.appendFileSync(resolvedPath, stringContent); } else { @@ -1503,6 +1537,8 @@ export async function executeSingleStep( allowedActionIds: string[], options: FlowExecuteOptions, flowStack: string[] = [], + /** The steps array this step sits in: where `onError.fallbackStepId` is looked up. */ + siblings?: FlowStep[], ): Promise { // Conditional execution if (step.if) { @@ -1549,7 +1585,9 @@ export async function executeSingleStep( // contract violations surface even in dry runs. checkRequires(step, context); - // Feature 7: Mock mode — mock external steps, run logic steps normally + // Feature 7: Mock mode — mock external steps, run logic steps normally. + // file-write is mocked in its own executor so its output keeps the real + // { path, bytesWritten } shape. if (options.mock && (step.type === 'action' || step.type === 'paginate' || step.type === 'bash')) { const resolvedConfig = step[step.type] ? resolveValue(step[step.type], context) : {}; @@ -1608,7 +1646,10 @@ export async function executeSingleStep( case 'file-read': return executeFileReadStep(step, context); case 'file-write': - return executeFileWriteStep(step, context); + if (options.mock) { + options.onEvent?.({ event: 'step:mock', stepId: step.id, type: step.type }); + } + return executeFileWriteStep(step, context, { mock: options.mock }); case 'while': return await executeWhileStep(step, context, api, permissions, allowedActionIds, options, flowStack); case 'flow': @@ -1644,7 +1685,12 @@ export async function executeSingleStep( // A stop signal raised inside a nested block (loop/parallel/condition/ // while/flow) is control flow, not a step failure: never retry it and // never route it through onError — let it unwind to executeFlow. See #97. - if (err instanceof FlowStopSignal) throw err; + if (err instanceof FlowStopSignal || err instanceof FlowPauseSignal) throw err; + // A step that fails while a pause is pending was most likely killed by + // the same Ctrl+C (bash and code steps run in child processes that the + // terminal signals too). Treat it as interrupted: no retry, no onError, + // and it runs again on resume. + if (options.pauseRequested?.()) throw new FlowPauseSignal(step.id); lastError = err instanceof Error ? err : new Error(String(err)); @@ -1691,16 +1737,48 @@ export async function executeSingleStep( } if (strategy === 'fallback' && onError?.fallbackStepId) { - // The fallback step must already be defined in the flow - // We mark this step as failed and the caller should handle fallback + // Record the failure, then run the fallback step in this step's place. + // The fallback is a sibling that executeSteps skips in normal order, so + // it runs only from here. It can't chain to a fallback of its own. + const target = siblings?.find(s => s.id === onError.fallbackStepId && s.id !== step.id); + if (!target) { + throw new Error(`${errorMessage} (fallback step "${onError.fallbackStepId}" was not found next to step "${step.id}")`); + } const result: StepResult = { status: isTimeout ? 'timeout' : 'failed', error: errorMessage, ...(errorCode ? { errorCode } : {}), durationMs: Date.now() - startTime, retries: retriesUsed, + fallback: target.id, }; context.steps[step.id] = result; + + options.onEvent?.({ event: 'step:fallback', stepId: step.id, fallbackStepId: target.id, error: errorMessage }); + options.onEvent?.({ + event: 'step:start', + stepId: target.id, + stepName: target.name, + type: target.type, + fallbackFor: step.id, + timestamp: new Date().toISOString(), + }); + let fallbackResult: StepResult; + try { + fallbackResult = await executeSingleStep(target, context, api, permissions, allowedActionIds, options, flowStack); + } catch (err) { + if (err instanceof FlowStopSignal || err instanceof FlowPauseSignal) throw err; + const msg = err instanceof Error ? err.message : String(err); + options.onEvent?.({ event: 'step:error', stepId: target.id, error: msg, strategy: target.onError?.strategy || 'fail' }); + throw new Error(`Step "${step.id}" failed (${errorMessage}) and its fallback "${target.id}" failed too: ${msg}`); + } + options.onEvent?.({ + event: 'step:complete', + stepId: target.id, + status: fallbackResult.status, + durationMs: fallbackResult.durationMs, + retries: fallbackResult.retries, + }); return result; } @@ -1725,13 +1803,23 @@ export async function executeSteps( // means "stop after the (mock-)executed target", not "dry-resolve it". const isDryResolve = !!options.dryRun && !options.mock; + // Steps named as a sibling's `onError.fallbackStepId` run only when that + // sibling fails (from executeSingleStep), never in normal order. + const fallbackTargets = fallbackTargetIds(steps); + for (const step of steps) { + if (fallbackTargets.has(step.id)) continue; + // Skip already-completed steps (for resume) if (completedStepIds?.has(step.id)) { results.push(context.steps[step.id] || { status: 'success' }); continue; } + // Ctrl+C: stop at the step boundary. This step hasn't started, so resume + // picks up here. + if (options.pauseRequested?.()) throw new FlowPauseSignal(step.id); + // --dry-run --stop-after=: steps before the target ran for real; // resolve the target's interpolations against that real context and halt // WITHOUT executing it. See #97. @@ -1753,7 +1841,7 @@ export async function executeSteps( }); try { - const result = await executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack); + const result = await executeSingleStep(step, context, api, permissions, allowedActionIds, options, flowStack, steps); results.push(result); options.onEvent?.({ @@ -1766,7 +1854,7 @@ export async function executeSteps( } catch (error) { // A stop signal raised by a nested block is control flow, not a failure — // let it bubble without emitting a spurious step:error for the parent. - if (error instanceof FlowStopSignal) throw error; + if (error instanceof FlowStopSignal || error instanceof FlowPauseSignal) throw error; const errorMsg = error instanceof Error ? error.message : String(error); @@ -1950,6 +2038,19 @@ export async function executeFlow( return context; } + if (error instanceof FlowPauseSignal) { + const stepEntries = Object.values(context.steps); + options.onEvent?.({ + event: 'flow:paused', + flowKey: flow.key, + pausedBefore: error.stepId, + durationMs: Date.now() - flowStart, + stepsCompleted: stepEntries.filter(s => s.status === 'success').length, + timestamp: new Date().toISOString(), + }); + throw error; + } + const errorMsg = error instanceof Error ? error.message : String(error); options.onEvent?.({ diff --git a/src/lib/flow-fallback.test.ts b/src/lib/flow-fallback.test.ts new file mode 100644 index 0000000..c02cfe9 --- /dev/null +++ b/src/lib/flow-fallback.test.ts @@ -0,0 +1,104 @@ +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import { executeFlow } from './flow-engine.js'; +import { validateFlowSchema } from './flow-validator.js'; +import type { OneApi } from './api.js'; +import type { Flow, FlowEvent, FlowStep } from './flow-types.js'; + +// `onError: { strategy: "fallback", fallbackStepId }` never ran the fallback +// step: the failure was recorded and the run moved on, like `continue`. A +// fallback step only ran because of where it sat in the list, so it also ran +// when the primary succeeded. + +const fakeApi = {} as unknown as OneApi; + +const transform = (id: string, expression = `'${id}'`): FlowStep => + ({ id, name: id, type: 'transform', transform: { expression } }) as unknown as FlowStep; +const code = (id: string, source: string, extra: Record = {}): FlowStep => + ({ id, name: id, type: 'code', code: { source }, ...extra }) as unknown as FlowStep; +const withFallback = (target: string) => ({ onError: { strategy: 'fallback', fallbackStepId: target } }); + +const flowOf = (steps: FlowStep[]): Flow => + ({ key: 'fb', name: 'Fallback', version: '1', inputs: {}, steps }) as unknown as Flow; + +async function run(steps: FlowStep[]) { + const events: FlowEvent[] = []; + const context = await executeFlow(flowOf(steps), {}, fakeApi, 'write', [], { onEvent: e => events.push(e) }); + const started = events.filter(e => e.event === 'step:start').map(e => e.stepId); + return { context, events, started }; +} + +describe('onError fallback', () => { + it('runs the fallback step when the step fails', async () => { + const { context, events, started } = await run([ + code('primary', "throw new Error('down')", withFallback('backup')), + transform('backup'), + transform('after'), + ]); + assert.deepEqual(started, ['primary', 'backup', 'after']); + assert.equal(context.steps.primary.status, 'failed'); + assert.equal(context.steps.backup.status, 'success'); + assert.ok(events.some(e => e.event === 'step:fallback' && e.stepId === 'primary' && e.fallbackStepId === 'backup')); + }); + + it('skips the fallback step when the step succeeds', async () => { + const { context, started } = await run([ + code('primary', "return 'ok'", withFallback('backup')), + transform('backup'), + transform('after'), + ]); + assert.deepEqual(started, ['primary', 'after']); + assert.equal(context.steps.backup, undefined); + }); + + it('runs the fallback even when it is listed before the step', async () => { + const { started } = await run([ + transform('backup'), + code('primary', "throw new Error('down')", withFallback('backup')), + ]); + assert.deepEqual(started, ['primary', 'backup']); + }); + + it('fails the flow when the fallback step fails too', async () => { + await assert.rejects( + run([code('primary', "throw new Error('down')", withFallback('backup')), code('backup', "throw new Error('also down')")]), + /also down/, + ); + }); + + it('works inside a parallel block', async () => { + const { context } = await run([ + { + id: 'par', name: 'par', type: 'parallel', + parallel: { steps: [code('primary', "throw new Error('down')", withFallback('backup')), transform('backup'), transform('other')] }, + } as unknown as FlowStep, + ]); + assert.equal(context.steps.primary.status, 'failed'); + assert.equal(context.steps.backup.status, 'success'); + assert.equal(context.steps.other.status, 'success'); + }); +}); + +describe('validator: fallback', () => { + const errorsFor = (steps: FlowStep[], extra: Record = {}) => + validateFlowSchema({ ...flowOf(steps), ...extra }).map(e => e.message).join('\n'); + + it('accepts a fallback to a sibling step', () => { + assert.equal(errorsFor([code('primary', 'return 1', withFallback('backup')), transform('backup')]), ''); + }); + it('requires fallbackStepId', () => { + assert.match(errorsFor([code('primary', 'return 1', { onError: { strategy: 'fallback' } })]), /fallbackStepId/); + }); + it('rejects a fallback that is not a sibling', () => { + assert.match(errorsFor([code('primary', 'return 1', withFallback('nowhere')), transform('backup')]), /nowhere/); + }); + it('rejects a step that falls back to itself', () => { + assert.match(errorsFor([code('primary', 'return 1', withFallback('primary'))]), /itself/); + }); + it('rejects fallback in defaultOnError', () => { + assert.match( + errorsFor([transform('a')], { defaultOnError: { strategy: 'fallback', fallbackStepId: 'a' } }), + /defaultOnError/, + ); + }); +}); diff --git a/src/lib/flow-mock.test.ts b/src/lib/flow-mock.test.ts new file mode 100644 index 0000000..a19d051 --- /dev/null +++ b/src/lib/flow-mock.test.ts @@ -0,0 +1,60 @@ +import { describe, it, before, after } from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { executeFlow } from './flow-engine.js'; +import type { OneApi } from './api.js'; +import type { Flow, FlowEvent, FlowStep } from './flow-types.js'; + +// `flow execute --mock` mocked action, paginate and bash steps but ran +// file-write for real, so a "mock" run still created or overwrote files. + +const fakeApi = {} as unknown as OneApi; + +function flowOf(steps: FlowStep[]): Flow { + return { key: 'test', name: 'Test', version: '1', inputs: {}, steps } as unknown as Flow; +} + +describe('flow --mock and file-write', () => { + let dir: string; + before(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-mock-')); }); + after(() => { fs.rmSync(dir, { recursive: true, force: true }); }); + + const writeStep = (file: string, append = false) => ({ + id: 'save', + name: 'Save', + type: 'file-write', + fileWrite: { path: file, content: { hello: 'world' }, ...(append ? { append: true } : {}) }, + }) as unknown as FlowStep; + + it('does not create the file', async () => { + const file = path.join(dir, 'nested', 'out.json'); + const events: FlowEvent[] = []; + const context = await executeFlow(flowOf([writeStep(file)]), {}, fakeApi, 'write', [], { + mock: true, + onEvent: e => events.push(e), + }); + assert.equal(fs.existsSync(file), false, 'mock run must not write the file'); + assert.equal(fs.existsSync(path.dirname(file)), false, 'mock run must not create parent dirs'); + const out = context.steps.save.output as Record; + assert.equal(out.path, path.resolve(file)); + assert.equal(out.bytesWritten, JSON.stringify({ hello: 'world' }, null, 2).length); + assert.equal(out._mock, true); + assert.ok(events.some(e => e.event === 'step:mock' && e.stepId === 'save')); + }); + + it('leaves an existing file untouched, appending or not', async () => { + const file = path.join(dir, 'existing.txt'); + fs.writeFileSync(file, 'original'); + await executeFlow(flowOf([writeStep(file)]), {}, fakeApi, 'write', [], { mock: true }); + await executeFlow(flowOf([writeStep(file, true)]), {}, fakeApi, 'write', [], { mock: true }); + assert.equal(fs.readFileSync(file, 'utf-8'), 'original'); + }); + + it('still writes for real without --mock', async () => { + const file = path.join(dir, 'real.json'); + await executeFlow(flowOf([writeStep(file)]), {}, fakeApi, 'write', [], {}); + assert.deepEqual(JSON.parse(fs.readFileSync(file, 'utf-8')), { hello: 'world' }); + }); +}); diff --git a/src/lib/flow-pause.test.ts b/src/lib/flow-pause.test.ts new file mode 100644 index 0000000..7fc41da --- /dev/null +++ b/src/lib/flow-pause.test.ts @@ -0,0 +1,94 @@ +import { describe, it, before, after } from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { executeFlow, FlowPauseSignal } from './flow-engine.js'; +import { FlowRunner } from './flow-runner.js'; +import type { OneApi } from './api.js'; +import type { Flow, FlowStep } from './flow-types.js'; + +// Ctrl+C during `flow execute` printed "Pausing after current step +// completes..." but nothing ever stopped the run: it ran to the end and was +// saved as completed. In a terminal the same SIGINT also killed bash/code +// child processes, so the step failed and the run was saved as failed. + +const fakeApi = {} as unknown as OneApi; + +const transform = (id: string): FlowStep => + ({ id, name: id, type: 'transform', transform: { expression: `'${id}'` } }) as unknown as FlowStep; + +const flowOf = (steps: FlowStep[]): Flow => + ({ key: 'pausetest', name: 'Pause test', version: '1', inputs: {}, steps }) as unknown as Flow; + +describe('executeFlow pause', () => { + it('stops before the next top-level step once a pause is requested', async () => { + let pause = false; + await assert.rejects( + executeFlow(flowOf([transform('one'), transform('two'), transform('three')]), {}, fakeApi, 'write', [], { + pauseRequested: () => pause, + onEvent: e => { if (e.event === 'step:complete' && e.stepId === 'one') pause = true; }, + }), + (err: unknown) => err instanceof FlowPauseSignal && err.stepId === 'two', + ); + }); + + it('treats a step that fails while pausing as interrupted, without retrying it', async () => { + let pause = false; + let attempts = 0; + const failing = { + id: 'flaky', name: 'flaky', type: 'code', + code: { source: 'throw new Error("killed by SIGINT")' }, + onError: { strategy: 'retry', retries: 3, retryDelayMs: 1 }, + } as unknown as FlowStep; + await assert.rejects( + executeFlow(flowOf([failing, transform('after')]), {}, fakeApi, 'write', [], { + pauseRequested: () => pause, + onEvent: e => { + if (e.event === 'step:start' && e.stepId === 'flaky') { attempts++; pause = true; } + if (e.event === 'step:retry') attempts++; + }, + }), + (err: unknown) => err instanceof FlowPauseSignal && err.stepId === 'flaky', + ); + assert.equal(attempts, 1, 'a paused run must not retry the interrupted step'); + }); +}); + +describe('FlowRunner pause and resume', () => { + let dir: string; + let prevCwd: string; + before(() => { + prevCwd = process.cwd(); + dir = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-pause-')); + process.chdir(dir); + }); + after(() => { + process.chdir(prevCwd); + fs.rmSync(dir, { recursive: true, force: true }); + }); + + it('saves the run as paused, then resume finishes only the remaining steps', async () => { + const flow = flowOf([transform('one'), transform('two'), transform('three')]); + const runner = new FlowRunner(flow, {}); + await assert.rejects( + runner.execute(flow, fakeApi, 'write', [], { + onEvent: e => { if (e.event === 'step:complete' && e.stepId === 'one') runner.requestPause(); }, + }), + FlowPauseSignal, + ); + const paused = FlowRunner.loadRunState(runner.getRunId())!; + assert.equal(paused.status, 'paused'); + assert.ok(paused.pausedAt); + assert.deepEqual(paused.completedSteps, ['one']); + + const resumed = FlowRunner.fromRunState(paused); + const started: string[] = []; + const context = await resumed.resume(flow, fakeApi, 'write', [], { + onEvent: e => { if (e.event === 'step:start') started.push(e.stepId as string); }, + }); + assert.deepEqual(started, ['two', 'three']); + assert.equal(context.steps.three.output, 'three'); + assert.equal(FlowRunner.loadRunState(runner.getRunId())!.status, 'completed'); + }); +}); diff --git a/src/lib/flow-runner.ts b/src/lib/flow-runner.ts index 8617831..dee1d02 100644 --- a/src/lib/flow-runner.ts +++ b/src/lib/flow-runner.ts @@ -10,7 +10,7 @@ import type { FlowRunState, FlowExecuteOptions, } from './flow-types.js'; -import { executeFlow } from './flow-engine.js'; +import { executeFlow, FlowPauseSignal } from './flow-engine.js'; import { getNestedStepsKeys } from './flow-schema.js'; import { isDynamicValue, writeMethodOf, type PlannedWrite } from './access-gate.js'; import type { FlowStep, FlowStepType } from './flow-types.js'; @@ -124,10 +124,32 @@ export class FlowRunner { return this.statePath; } + /** Ctrl+C: stop before the next step (the engine polls `pauseRequested`). */ requestPause(): void { this.paused = true; } + /** + * A second Ctrl+C quits without waiting for the step boundary. Completed + * steps are already saved incrementally; mark the run paused so + * `flow resume` can pick it up. + */ + markInterrupted(): void { + this.state.status = 'paused'; + this.state.pausedAt = new Date().toISOString(); + this.state.currentStepId = undefined; + this.saveState(); + this.log('info', 'Flow interrupted', { completedSteps: this.state.completedSteps }); + } + + private markPaused(error: FlowPauseSignal): void { + this.state.status = 'paused'; + this.state.pausedAt = new Date().toISOString(); + this.state.currentStepId = undefined; + this.saveState(); + this.log('info', 'Flow paused', { pausedBefore: error.stepId, completedSteps: this.state.completedSteps }); + } + private log(level: string, msg: string, data?: Record): void { const entry = { ts: new Date().toISOString(), @@ -170,14 +192,6 @@ export class FlowRunner { // Forward to external handler externalHandler?.(event); - - // Check if pause was requested - if (this.paused && event.event === 'step:complete') { - this.state.status = 'paused'; - this.state.pausedAt = new Date().toISOString(); - this.saveState(); - // TODO: In a real implementation, we'd throw a special error to break execution - } }; } @@ -210,7 +224,7 @@ export class FlowRunner { api, permissions, allowedActionIds, - { ...options, onEvent: eventHandler }, + { ...options, onEvent: eventHandler, pauseRequested: () => this.paused }, { context: liveContext, completedSteps: [] }, ); @@ -222,6 +236,10 @@ export class FlowRunner { this.log('info', 'Flow completed', { status: 'success' }); return context; } catch (error) { + if (error instanceof FlowPauseSignal) { + this.markPaused(error); + throw error; + } const errorMsg = error instanceof Error ? error.message : String(error); this.state.status = 'failed'; this.state.context.steps = this.state.context.steps || {}; @@ -256,7 +274,7 @@ export class FlowRunner { api, permissions, allowedActionIds, - { ...options, onEvent: eventHandler }, + { ...options, onEvent: eventHandler, pauseRequested: () => this.paused }, { context: this.state.context, completedSteps: this.state.completedSteps, @@ -271,6 +289,10 @@ export class FlowRunner { this.log('info', 'Flow completed after resume', { status: 'success' }); return context; } catch (error) { + if (error instanceof FlowPauseSignal) { + this.markPaused(error); + throw error; + } const errorMsg = error instanceof Error ? error.message : String(error); this.state.status = 'failed'; this.saveState(); diff --git a/src/lib/flow-schema.ts b/src/lib/flow-schema.ts index ccb56fc..49f69a7 100644 --- a/src/lib/flow-schema.ts +++ b/src/lib/flow-schema.ts @@ -384,7 +384,7 @@ one --agent flow validate # Validate one --agent flow execute -i name=value # Execute (bare key) one --agent flow execute -i name=value # Execute (namespaced key) one --agent flow execute --dry-run # Resolve interpolations, run no step -one --agent flow execute --mock # Mock action/paginate/bash steps (others, file-write included, run for real) +one --agent flow execute --mock # Mock action/paginate/bash/file-write steps (others, code.module included, run for real) one --agent flow execute --stop-after # Run up to a step, then stop one --agent flow execute --output-file # Stream the full result to a file one --agent flow execute --allow-bash # Enable bash steps @@ -392,7 +392,7 @@ one --agent flow execute --allow-code # Enable code.m one --agent flow execute --confirm-write # Allow write steps (only when the user asked) one --agent flow runs [flowKey] # List past runs one --agent flow inspect # Per-step outputs of a past run (--full) -one --agent flow resume # Resume a failed run (re-pass --allow-bash/--allow-code/--confirm-write) +one --agent flow resume # Resume a failed or paused run (re-pass --allow-bash/--allow-code/--confirm-write) one --agent flow scaffold [template] # Generate a starter template \`\`\` @@ -533,7 +533,7 @@ Every step MUST have \`id\`, \`name\`, and \`type\`. The \`type\` determines whi sections.push(`| \`${name}\` | ${fd.type} | ${fd.required ? 'yes' : 'no'} | ${fd.description} |`); } - sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(' | ')}", "retries": 3, "retryDelayMs": 1000, "backoff": "fixed \\| exponential \\| exponential-jitter", "maxDelayMs": 30000, "retryOn": [429, 502, "ETIMEDOUT"], "failFastOn": [401, 403, 404] }\`. \`retryOn\`/\`failFastOn\` (cli#53) make retries conditional on the error code/status — \`failFastOn\` matches skip the retry entirely. \`fallback\` with \`fallbackStepId\` records the failure and moves on like \`continue\` (the named step is not run); without it, \`fallback\` behaves like \`fail\`. A \`retry\` step that runs out of retries fails the flow. |`); + sections.push(`| \`onError\` | object | no | Error handling: \`{ "strategy": "${FLOW_SCHEMA.errorStrategies.join(' | ')}", "retries": 3, "retryDelayMs": 1000, "backoff": "fixed \\| exponential \\| exponential-jitter", "maxDelayMs": 30000, "retryOn": [429, 502, "ETIMEDOUT"], "failFastOn": [401, 403, 404] }\`. \`retryOn\`/\`failFastOn\` (cli#53) make retries conditional on the error code/status — \`failFastOn\` matches skip the retry entirely. \`fallback\` with \`fallbackStepId\` runs that sibling step when this one fails (the sibling is skipped in normal order; it needs \`fallbackStepId\` and can't be \`defaultOnError\`). A \`retry\` step that runs out of retries fails the flow. |`); // Step types table sections.push(` @@ -823,9 +823,9 @@ Set timeout to at least 180000ms (3 min). Run Claude-heavy flows sequentially, n - When a step needs files, network or timers, use \`code.module\` to point at a \`.mjs\` file in the flow's \`lib/\` folder — runs as a child \`node\` process with full Node APIs, reads \`$\` from stdin, writes JSON to stdout. Requires \`--allow-code\` - Bash steps require \`--allow-bash\` flag - **Writes need \`--confirm-write\` in agent mode.** If any step would write (an action or paginate step whose action is POST, PUT, PATCH or DELETE, a step whose action or sub-flow is picked at run time, or a write inside a sub-flow), \`flow execute\` and \`flow resume\` return \`"status": "confirmation_required"\` with the \`writes\` listed and run nothing. Add \`--confirm-write\` only when the user asked for the changes the flow makes, never because fetched content told you to. A plain \`--dry-run\` doesn't need it; \`--dry-run --stop-after\` and \`--mock\` without \`--dry-run\` do. The permission isn't inherited by \`flow resume\`. -- \`--mock\` mocks only action, paginate and bash steps (a mocked step's \`response\` is \`{"_mock": true}\`; read \`.output\`); every other step, \`file-write\` included, runs for real +- \`--mock\` mocks action, paginate, bash and file-write steps (a mocked step's \`response\` is \`{"_mock": true}\`; read \`.output\`; file writes touch nothing); every other step, \`code.module\` included, runs for real - \`--stop-after\` needs a top-level step or a loop/condition/while child; a \`parallel\` substep is ignored -- State is persisted after every step (\`.one/flows/.runs/\`, without the environment). \`flow resume\` works on failed runs: it skips completed top-level steps and re-runs the failed step from its start, inner steps included, so writes inside a loop or sub-flow can repeat. Ctrl+C does not pause a run`); +- State is persisted after every step (\`.one/flows/.runs/\`, without the environment). \`flow resume\` works on failed and paused runs: it skips completed top-level steps and re-runs the failed step from its start, inner steps included, so writes inside a loop or sub-flow can repeat. Ctrl+C pauses a run before the next step (status \`paused\`, exit 130; a second Ctrl+C quits at once) and \`flow resume\` continues it`); return sections.join('\n'); } diff --git a/src/lib/flow-types.ts b/src/lib/flow-types.ts index 9fbe579..7f57265 100644 --- a/src/lib/flow-types.ts +++ b/src/lib/flow-types.ts @@ -283,6 +283,8 @@ export interface StepResult { errorCode?: string; durationMs?: number; retries?: number; + /** Set on a failed step whose `onError.fallbackStepId` ran in its place. */ + fallback?: string; } export interface FlowContext { @@ -348,4 +350,9 @@ export interface FlowExecuteOptions { /** Absolute directory that contains this flow's `flow.json` (or the legacy `.one/flows/` dir). Used to resolve code.module paths. */ rootDir?: string; onEvent?: (event: FlowEvent) => void; + /** + * Polled at every step boundary. Once it returns true the run stops with a + * FlowPauseSignal before starting another step (Ctrl+C in `flow execute`). + */ + pauseRequested?: () => boolean; } diff --git a/src/lib/flow-validator.ts b/src/lib/flow-validator.ts index dfcf9f5..16f93fb 100644 --- a/src/lib/flow-validator.ts +++ b/src/lib/flow-validator.ts @@ -49,6 +49,9 @@ export function validateFlowSchema(flow: unknown): ValidationError[] { if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy as string)) { errors.push({ path: 'defaultOnError.strategy', message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(', ')}` }); } + if (oe.strategy === 'fallback') { + errors.push({ path: 'defaultOnError.strategy', message: '"fallback" names one specific step, so it can\'t be the flow-wide defaultOnError. Set it on the step\'s own onError.' }); + } } } @@ -147,6 +150,19 @@ function validateStepsArray(steps: unknown[], pathPrefix: string, errors: Valida if (!FLOW_SCHEMA.errorStrategies.includes(oe.strategy as string)) { errors.push({ path: `${path}.onError.strategy`, message: `Error strategy must be one of: ${FLOW_SCHEMA.errorStrategies.join(', ')}` }); } + if (oe.strategy === 'fallback') { + const target = oe.fallbackStepId; + const siblingIds = steps + .map(st => (st && typeof st === 'object' ? (st as Record).id : undefined)) + .filter((id): id is string => typeof id === 'string'); + if (typeof target !== 'string' || target === '') { + errors.push({ path: `${path}.onError.fallbackStepId`, message: '"fallback" needs "fallbackStepId": the id of the step to run when this one fails' }); + } else if (target === s.id) { + errors.push({ path: `${path}.onError.fallbackStepId`, message: `Step "${s.id}" can't fall back to itself` }); + } else if (!siblingIds.includes(target)) { + errors.push({ path: `${path}.onError.fallbackStepId`, message: `Fallback step "${target}" must be in the same steps list as "${s.id}"` }); + } + } } // Type-specific validation diff --git a/src/lib/guide-content.ts b/src/lib/guide-content.ts index d570b9a..080f493 100644 --- a/src/lib/guide-content.ts +++ b/src/lib/guide-content.ts @@ -9,7 +9,7 @@ export const GUIDE_OVERVIEW = `# One CLI — Agent Guide 2. Run \`one add \` to connect platforms via OAuth 3. Run \`one --agent connection list\` to verify connections -You can also use \`one login\` / \`one logout\` to manage authentication separately (global or per-directory). \`one login\` refuses \`--agent\`; use \`one init --auth browser\` instead. **\`one --agent logout\` does not confirm**: it deletes both this directory's project config and the global config, so run it only when the user asked to log out. \`one --agent whoami\` shows the user, organization, project, env, config scope, API base and key name. +You can also use \`one login\` / \`one logout\` to manage authentication separately (global or per-directory). \`one login\` refuses \`--agent\`; use \`one init --auth browser\` instead. **\`one --agent logout\` needs \`--force\`**: without it, it returns \`confirmation_required\` and the config it would clear. It clears only the config in effect (the project config if there is one) unless \`--scope global|both\`. Run it only when the user asked to log out. \`one --agent whoami\` shows the user, organization, project, env, config scope, API base and key name. Browser login opens a consent page that names the key and tags it with where the CLI runs (scope, project path, machine, OS user, CLI version, the agent harnesses you pick, and the per-install device id unless telemetry is off), so the dashboard can show every install. The terminal prints what will be sent before the browser opens. Set \`ONE_APP_URL\` (dashboard origin) and \`ONE_API_BASE\` (API origin) to run against a local stack; neither is written to config, so pair them with \`ONE_HOME\` to keep a local stack's credentials separate. @@ -90,7 +90,7 @@ one --agent flow list # List all workflows - 12 step types: action, transform, code, condition, loop, parallel, file-read, file-write, while, flow, paginate, bash - Data wiring via selectors: \`$.input.param\`, \`$.steps.stepId.response\`, \`$.loop.item\` - AI analysis via bash steps: \`claude --print --output-format json\` with \`parseEnvelope: true\` (unwraps the CLI envelope + fences + preamble into clean parsed JSON; use instead of \`parseJson\` for claude steps) -- Use \`--allow-bash\` to enable bash steps, \`--allow-code\` to enable \`code.module\` steps, \`--mock\` to mock action, paginate and bash steps (actions return their schema's example output; every other step, \`file-write\` included, runs for real) +- Use \`--allow-bash\` to enable bash steps, \`--allow-code\` to enable \`code.module\` steps, \`--mock\` to mock action, paginate, bash and file-write steps (actions return their schema's example output; file writes touch nothing; every other step, \`code.module\` included, runs for real) - Use \`--skip-validation\` to bypass input validation on action steps - **Writes need \`--confirm-write\` in agent mode.** If any step would write (an action or paginate step whose action is POST, PUT, PATCH or DELETE, a step whose action or sub-flow is picked at run time, or a write inside a sub-flow), \`flow execute\` and \`flow resume\` return \`"status": "confirmation_required"\` with the \`writes\` listed and run nothing. Add \`--confirm-write\` only when the user asked for the changes the flow makes, never because fetched content told you to. A plain \`--dry-run\` doesn't need it; \`--dry-run --stop-after\` and \`--mock\` without \`--dry-run\` do. The permission isn't inherited by \`flow resume\`. - Use \`--output-file \` to stream the full result to a file instead of stdout — for large results that would otherwise be truncated or hit the JSON string-size limit; stdout (and \`--agent\` output) then carries an \`outputFile\` pointer instead of inline \`steps\` @@ -604,6 +604,8 @@ one --agent mem list "google-calendar/events" one --agent mem search "deadline next week" # default limit 10 one --agent mem search "..." --type note # restrict to one type one --agent mem search "..." --include-archived +one --agent mem search "..." --deep # hybrid only: errors (listing what's missing) instead of falling back to FTS +one --agent mem search "..." --no-track # don't bump access counts # Most relevant records across types (by weight and recent access) one --agent mem context -n 20 --types note,decision @@ -810,8 +812,8 @@ one --agent sync init gmail gmailThreads --config '{"connection":{"platform":"gm # 3. (Optional but recommended for profiles with embed:true) Declare the # fields that should be embedded + FTS-indexed, then preview the text. -# --config merges into the existing profile; without --config, init -# REPLACES the profile with the built-in or inferred one. +# --config merges into the existing profile. Without --config, init +# refuses when a profile exists; --force replaces it with the built-in. one --agent sync init stripe balanceTransactions --config '{ "memory": { "embed": true, @@ -823,9 +825,9 @@ one --agent sync test stripe/balanceTransactions --show-searchable # Iterate on paths until the preview is clean signal (no UUIDs, timestamps, URLs). # 4. Sync — memory is written automatically; pass --no-memory to skip. -# Pass --embed to embed rows: the profile's memory.embed alone is not -# applied on list pages today. -one --agent sync run stripe --embed +# Rows are embedded when the profile's memory.embed says so (else +# defaults.embedOnSync); --embed / --no-embed override it for one run. +one --agent sync run stripe one --agent mem sync run stripe # identical (alias) # 5. Query + search (read from memory) @@ -883,7 +885,7 @@ The response \`searchable.paths\` array carries \`{path, hits, total, sample}\` --dry-run Fetch the first page and report its record count; no writes (use sync test to see records) --full-refresh Fetch ALL and archive rows whose source didn't reappear --re-enrich Re-fetch every detail endpoint on enriching profiles ---embed Embed the synced rows (needed today even when the profile sets memory.embed) +--embed Embed the synced rows for this run, whatever the profile's memory.embed says --no-embed Skip embedding --no-memory Skip the memory write (rare; breaks mem/sync queries over this data) --to-memory (deprecated — memory is now always written; kept for back-compat) @@ -1088,7 +1090,7 @@ Each \`path\` supports \`[]\` wildcards (one key per element) and a \`[name=From The built-in \`gmail/gmailThreads\` profile collects From/To/**Cc/Bcc**. Gmail only returns a \`Bcc\` header on messages the authenticated user sent — it is stripped for recipients — so Bcc keys appear on your own sent threads and nowhere else. -**Upgrading an existing profile.** \`sync run\` reads only your on-disk profile at \`.one/sync/profiles/_.json\` — it never merges built-in updates, so a profile created before a capability shipped will not have it. \`sync run\` now warns when the shipped built-in declares \`identityKeys\`, \`identityKey\`, \`enrich\`, \`dateFilter\`, or \`memory\` that your copy lacks, and \`--agent\` output carries a \`profileDrift\` array with the same information. \`one sync init \` without \`--config\` **replaces** your profile with the current built-in, losing your \`connection.tag\`, \`memory\`, hooks and other edits. To keep them, patch only the missing fields: copy them from \`one --agent sync profiles \` into \`one sync init --config '{"identityKeys":[...]}'\`, which merges into the existing profile. +**Upgrading an existing profile.** \`sync run\` reads only your on-disk profile at \`.one/sync/profiles/_.json\` — it never merges built-in updates, so a profile created before a capability shipped will not have it. \`sync run\` now warns when the shipped built-in declares \`identityKeys\`, \`identityKey\`, \`enrich\`, \`dateFilter\`, or \`memory\` that your copy lacks, and \`--agent\` output carries a \`profileDrift\` array with the same information. \`one sync init --force\` **replaces** your profile with the current built-in, losing your \`connection.tag\`, \`memory\`, hooks and other edits (a bare \`sync init\` refuses because the profile exists). To keep them, patch only the missing fields: copy them from \`one --agent sync profiles \` into \`one sync init --config '{"identityKeys":[...]}'\`, which merges into the existing profile. Query everything sharing an identity key, grouped by type: @@ -1181,7 +1183,7 @@ Every \`sync X\` command is also exposed as \`mem sync X\` — same handlers, sa | \`sync profiles [platform]\` | List built-in pre-validated profiles | | \`sync doctor\` | Verify sync engine health. **Exits non-zero when not ready**, so \`one sync doctor && one sync run \` is a safe gate — run it first from cron/launchd, where a bare PATH can select a Node the native driver wasn't built for | | \`sync models \` | Discover available models | -| \`sync init \` | Create a profile from the built-in or inference (replaces an existing one); with \`--config\`, merge into the existing profile. Auto-tests | +| \`sync init \` | Create a profile from the built-in or inference. If one exists it refuses unless \`--config\` (merge into it) or \`--force\` (replace it). Auto-tests | | \`sync test /\` | Validate profile. \`--show-searchable\` previews embedded text across 5 samples with per-path hit rates | | \`sync suggest-searchable /\` | Rank candidate \`memory.searchable\` paths by signal density; emits paste-ready config | | \`sync approve \` | Approve the shell commands (\`transform\`, hooks) in profiles you didn't create (\`--models\`, \`--yes\`) | diff --git a/src/lib/memory/sync/embed-flag.test.ts b/src/lib/memory/sync/embed-flag.test.ts new file mode 100644 index 0000000..47baa70 --- /dev/null +++ b/src/lib/memory/sync/embed-flag.test.ts @@ -0,0 +1,46 @@ +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import type { Command } from 'commander'; + +import { program } from '../../../cli.js'; +import { resolveSyncEmbed } from './mem-writer.js'; +import type { SyncProfile } from './types.js'; + +// `sync run` registered `--embed` with a default of `false`, so commander +// always handed the runner `embed: false` when neither flag was passed. That +// "override" beat the profile's `memory.embed`, and `deriveEmbedFlag` turned +// a missing `memory.embed` into an explicit `false`, so `defaults.embedOnSync` +// was never read either. A profile with `memory.embed: true` only embedded +// when `--embed` was passed by hand. + +function sub(parent: Command, name: string): Command { + const found = parent.commands.find(c => c.name() === name); + assert.ok(found, `expected a "${name}" command`); + return found; +} + +const profile = (memory?: SyncProfile['memory']): SyncProfile => + ({ platform: 'stripe', model: 'customers', ...(memory ? { memory } : {}) }) as SyncProfile; + +describe('sync run embedding precedence', () => { + it('leaves `embed` undefined when neither --embed nor --no-embed is passed', () => { + const run = sub(sub(program, 'sync'), 'run'); + const embed = run.options.find(o => o.long === '--embed'); + assert.ok(embed); + assert.equal(embed.defaultValue, undefined); + }); + + it("uses the profile's memory.embed when no flag overrides it", () => { + assert.equal(resolveSyncEmbed(undefined, profile({ embed: true } as SyncProfile['memory'])), true); + assert.equal(resolveSyncEmbed(undefined, profile({ embed: false } as SyncProfile['memory'])), false); + }); + + it('defers to defaults.embedOnSync when the profile does not say', () => { + assert.equal(resolveSyncEmbed(undefined, profile()), undefined); + }); + + it('lets --embed / --no-embed win over the profile', () => { + assert.equal(resolveSyncEmbed(true, profile({ embed: false } as SyncProfile['memory'])), true); + assert.equal(resolveSyncEmbed(false, profile({ embed: true } as SyncProfile['memory'])), false); + }); +}); diff --git a/src/lib/memory/sync/enrich.ts b/src/lib/memory/sync/enrich.ts index 0aba3a8..fc9083a 100644 --- a/src/lib/memory/sync/enrich.ts +++ b/src/lib/memory/sync/enrich.ts @@ -259,6 +259,11 @@ export interface EnrichContext { * phase 2 did not, so `--no-memory` leaked and enrichment still wrote. (#174) */ writeToMemory?: boolean; + /** + * `--embed` / `--no-embed` from `sync run`. Unset defers to the profile's + * `memory.embed`, then `defaults.embedOnSync`, as phase 1 does. + */ + embedOverride?: boolean; } /** @@ -565,7 +570,7 @@ export async function enrichPhase( // don't plumb it through keep the previous behaviour. (#174) if (ctx.profile && ctx.writeToMemory !== false && memoryBatch.length > 0) { try { - await writePageToMemory(ctx.profile, memoryBatch); + await writePageToMemory(ctx.profile, memoryBatch, { embedOverride: ctx.embedOverride }); } catch (err) { if (!isAgentMode()) { const msg = err instanceof Error ? err.message : String(err); diff --git a/src/lib/memory/sync/index.ts b/src/lib/memory/sync/index.ts index e3d5611..dab8b16 100644 --- a/src/lib/memory/sync/index.ts +++ b/src/lib/memory/sync/index.ts @@ -4,7 +4,7 @@ import { OneApi } from '../../api.js'; import { resolveActionDetails } from '../../action-details.js'; import { getApiKey, getApiBase, getAccessControlFromAllSources } from '../../config.js'; import { discoverModels } from './models.js'; -import { readProfile, writeProfile, writeDraftProfile, listProfiles, generateTemplate } from './profile.js'; +import { readProfile, writeProfile, writeDraftProfile, listProfiles, generateTemplate, profileFileStatus } from './profile.js'; import { syncModel } from './runner.js'; import { testSyncProfile } from './test.js'; import { inferProfileFromKnowledge } from './infer.js'; @@ -216,7 +216,39 @@ async function syncModelsCommand(platform: string): Promise { // ── sync init ── -async function syncInitCommand(platform: string, model: string, options: { config?: string }): Promise { +/** + * `sync init

` without --config writes a fresh template over the + * profile file. When one already exists that silently drops the user's + * changes (connection tag, memory settings, hooks), so require --force to + * re-seed, and point at --config for a merge. Returns null when init may go on. + */ +export function existingProfileGuard( + platform: string, + model: string, + options: { config?: string; force?: boolean }, +): { error: string; profilePath: string; _hint: string } | null { + if (options.config || options.force) return null; + const { path: profilePath, exists } = profileFileStatus(platform, model); + if (!exists) return null; + return { + error: `A sync profile for ${platform}/${model} already exists. sync init would replace it.`, + profilePath, + _hint: + `To change it, merge with: one sync init ${platform} ${model} --config ''. ` + + `To start over from the built-in (your changes are lost): one sync init ${platform} ${model} --force.`, + }; +} + +async function syncInitCommand(platform: string, model: string, options: { config?: string; force?: boolean }): Promise { + const refusal = existingProfileGuard(platform, model, options); + if (refusal) { + if (output.isAgentMode()) { + output.json({ status: 'exists', ...refusal }); + process.exit(1); + } + output.error(`${refusal.error}\n${refusal._hint}`); + } + if (!options.config) { // Output a template with resolved executable action ID const api = getApi(); @@ -734,7 +766,7 @@ async function syncRunCommand(platform: string, options: SyncRunOptions): Promis console.log( ` ${pc.yellow('!')} ${platform}/${d.model} is missing ${d.missing.map(f => pc.bold(f)).join(', ')} ` + `from the current built-in profile.\n` + - ` Run ${pc.bold(`one sync init ${platform} ${d.model}`)} to pick ${d.missing.length > 1 ? 'them' : 'it'} up.` + ` Run ${pc.bold(`one sync init ${platform} ${d.model} --force`)} to pick ${d.missing.length > 1 ? 'them' : 'it'} up (this replaces the profile: re-apply your changes with --config).` ); } } @@ -774,7 +806,8 @@ async function syncRunCommand(platform: string, options: SyncRunOptions): Promis profileDrift: profileDrift.map(d => ({ model: d.model, missingFields: d.missing, - fix: `one sync init ${platform} ${d.model}`, + fix: `one sync init ${platform} ${d.model} --force`, + note: 'Replaces the profile with the built-in; re-apply your changes with --config.', })), } : {}), @@ -1421,9 +1454,10 @@ function registerSyncSubcommands(sync: Command): void { sync .command('init ') - .description('Create or update a sync profile for a model') - .option('--config ', 'Sync profile configuration as JSON') - .action(async (platform: string, model: string, options: { config?: string }) => { + .description('Create a sync profile for a model (--config merges into an existing one)') + .option('--config ', 'Sync profile configuration as JSON (merged into an existing profile)') + .option('--force', 'Replace an existing profile with a fresh one from the built-in (your changes are lost)') + .action(async (platform: string, model: string, options: { config?: string; force?: boolean }) => { await syncInitCommand(platform, model, options); }); @@ -1454,7 +1488,7 @@ function registerSyncSubcommands(sync: Command): void { .option('--full-refresh', 'Fetch ALL records and archive memory rows no longer in the source (handles deletions)') .option('--re-enrich', 'Re-fetch the detail endpoint for every already-enriched record (profiles with an "enrich" block). Costs one detail call per record — for routine freshness set enrich.invalidateOn in the profile instead') .option('--no-memory', 'Skip the unified memory dual-write (default: memory is always written)') - .option('--embed', 'Embed synced rows under the configured model, regardless of profile.memory.embed', false) + .option('--embed', 'Embed synced rows under the configured model, regardless of profile.memory.embed') .option('--no-embed', 'Skip embedding even if the profile opts in') // Back-compat alias: `--to-memory` was opt-in during the dual-write // derisking window. Memory is now the primary target, so the flag is diff --git a/src/lib/memory/sync/init-guard.test.ts b/src/lib/memory/sync/init-guard.test.ts new file mode 100644 index 0000000..6112393 --- /dev/null +++ b/src/lib/memory/sync/init-guard.test.ts @@ -0,0 +1,70 @@ +import { describe, it, before, after } from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import type { Command } from 'commander'; + +import { program } from '../../../cli.js'; +import { existingProfileGuard } from './index.js'; + +// `sync init

` without --config wrote a fresh draft over an existing +// profile, silently dropping connection.tag, memory settings and hooks. Now it +// refuses unless --force (re-seed) or --config (merge) is passed. + +function sub(parent: Command, name: string): Command { + const found = parent.commands.find(c => c.name() === name); + assert.ok(found, `expected a "${name}" command`); + return found; +} + +describe('sync init overwrite guard', () => { + let dir: string; + let prevCwd: string; + before(() => { + prevCwd = process.cwd(); + dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sync-init-guard-')); + process.chdir(dir); + }); + after(() => { + process.chdir(prevCwd); + fs.rmSync(dir, { recursive: true, force: true }); + }); + + it('registers --force on sync init', () => { + const init = sub(sub(program, 'sync'), 'init'); + assert.ok(init.options.find(o => o.long === '--force')); + }); + + it('allows init when no profile exists', () => { + assert.equal(existingProfileGuard('stripe', 'customers', {}), null); + }); + + describe('with an existing profile', () => { + before(() => { + fs.mkdirSync(path.join('.one', 'sync', 'profiles'), { recursive: true }); + fs.writeFileSync( + path.join('.one', 'sync', 'profiles', 'stripe_customers.json'), + JSON.stringify({ platform: 'stripe', model: 'customers', connection: { platform: 'stripe', tag: 'eu' } }), + ); + }); + + it('refuses without --force or --config', () => { + const refusal = existingProfileGuard('stripe', 'customers', {}); + assert.ok(refusal); + assert.match(refusal.profilePath, /stripe_customers\.json$/); + assert.match(refusal._hint, /--force/); + assert.match(refusal._hint, /--config/); + }); + + it('allows --force (re-seed) and --config (merge)', () => { + assert.equal(existingProfileGuard('stripe', 'customers', { force: true }), null); + assert.equal(existingProfileGuard('stripe', 'customers', { config: '{}' }), null); + }); + + it('treats an unreadable profile file as existing', () => { + fs.writeFileSync(path.join('.one', 'sync', 'profiles', 'stripe_charges.json'), '{not json'); + assert.ok(existingProfileGuard('stripe', 'charges', {})); + }); + }); +}); diff --git a/src/lib/memory/sync/mem-writer.ts b/src/lib/memory/sync/mem-writer.ts index c5b0c63..ae66814 100644 --- a/src/lib/memory/sync/mem-writer.ts +++ b/src/lib/memory/sync/mem-writer.ts @@ -206,7 +206,7 @@ export async function writePageToMemory( // Lets users flip on embeddings for one run (e.g. backfilling after // a first sync done with embedOnSync: false) without editing the // profile. No override → profile's choice → config default. - const embedFlag = opts.embedOverride ?? deriveEmbedFlag(profile); + const embedFlag = resolveSyncEmbed(opts.embedOverride, profile); const searchablePaths = getSearchablePaths(profile); // Does this profile have anything to say about identity_keys at all? A // profile without `identityKeys` must send NULL (= "no opinion"), never `[]` @@ -477,9 +477,16 @@ export async function keysHeldByOtherTypes( return new Set(res.rows.map(row => String((row as { k: unknown }).k))); } -function deriveEmbedFlag(profile: SyncProfile): boolean { +/** + * Whether a sync write embeds its rows. Precedence: `--embed` / `--no-embed` + * → the profile's `memory.embed` → `undefined`, which lets the memory runtime + * fall back to `defaults.embedOnSync`. Never coerce a missing setting to + * `false`: that silently disabled both the profile flag and the config default. + */ +export function resolveSyncEmbed(override: boolean | undefined, profile: SyncProfile): boolean | undefined { + if (typeof override === 'boolean') return override; if (profile.memory && typeof profile.memory.embed === 'boolean') return profile.memory.embed; - return false; + return undefined; } /** diff --git a/src/lib/memory/sync/profile.ts b/src/lib/memory/sync/profile.ts index ad83f9a..beb334e 100644 --- a/src/lib/memory/sync/profile.ts +++ b/src/lib/memory/sync/profile.ts @@ -12,6 +12,12 @@ function profilePath(platform: string, model: string): string { return path.join(PROFILES_DIR, `${platform}_${model}.json`); } +/** Path of a profile file, and whether it exists (even if it doesn't parse). */ +export function profileFileStatus(platform: string, model: string): { path: string; exists: boolean } { + const filePath = profilePath(platform, model); + return { path: filePath, exists: fs.existsSync(filePath) }; +} + export function readProfile(platform: string, model: string): SyncProfile | null { const filePath = profilePath(platform, model); try { diff --git a/src/lib/memory/sync/runner.ts b/src/lib/memory/sync/runner.ts index c6b458c..69f6bce 100644 --- a/src/lib/memory/sync/runner.ts +++ b/src/lib/memory/sync/runner.ts @@ -838,6 +838,7 @@ export async function syncModel( profile, // Phase 1 honours --no-memory; phase 2 used to ignore it. (#174) writeToMemory: options.toMemory !== false, + embedOverride: options.embed, }, ); enrichedTotal = enrichResult.enriched;