@bendyline/gezel-cli 1.1.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -89,16 +89,133 @@ gezel --home /path/to/another-home # standalone with an alternate home
89
89
  An explicit `--port 6228` remains available when you intentionally want a
90
90
  CLI-owned daemon on the canonical port.
91
91
 
92
+ ## Provider credentials
93
+
94
+ Manage provider keys through the service credential store, using stdin or an
95
+ existing environment variable so the value does not appear in command arguments:
96
+
97
+ ```bash
98
+ gezel secret list
99
+ gezel secret set braveSearchApiKey --env BRAVE_SEARCH_API_KEY --use-for-search
100
+ gezel secret set openaiApiKey --stdin < /path/to/private-key-file
101
+ gezel secret remove openaiApiKey
102
+ ```
103
+
104
+ `--use-for-search` (with `braveSearchApiKey`) also selects Brave as the
105
+ search provider while preserving its other settings. Without it, setting a
106
+ credential leaves provider selection unchanged. `secret list` gives the supported
107
+ names and whether each is configured; credentials are write-only and never
108
+ printed. All three commands support `--json`, and honor `--home` / `--connect`.
109
+ This covers the built-in provider credentials, including webhooks; it is not an
110
+ arbitrary environment-variable store. Storage uses the same native keyring or
111
+ encrypted fallback as the application.
112
+
113
+ Search also requires the selected environment to allow external services.
114
+ `gezel security external-services` shows that setting; append `on` or `off` to
115
+ change it explicitly while preserving all other security capabilities. This
116
+ permission covers model-initiated external services, including web search.
117
+ Saving a credential does not silently enable it.
118
+
119
+ `gezel model context <id> 65536` sets a local model's context window for its next
120
+ launch; omit the token count to inspect it, or use `auto` to clear the override.
121
+ Use `--provider llama-cpp|mlx|ds4` to select an engine (defaults to the platform's
122
+ local engine). This can bound memory use for unattended batch tasks.
123
+
124
+ `gezel model concurrency 1` limits the local engine to one inference slot and
125
+ reduces its context-cache reservation. This is useful for serial batches with
126
+ large models. It preserves other providers' limits; `--provider` selects an
127
+ engine, and `auto` restores automatic sizing. Omit the value to inspect it.
128
+
129
+ `gezel env indexing off` disables optional background workspace indexing in
130
+ the current directory's project (or `--project` target). Artifact-driven batch
131
+ workflows over large generated datasets can use this to avoid unnecessary
132
+ indexing. `on` restores it; omitting the value reports its current state.
133
+ Both settings commands support `--json` and the ordinary connection/home flags.
134
+
135
+ ## Batch craftbooks and repository workflows
136
+
137
+ `do` accepts positional parameters in the recipe's `paramSchema.properties`
138
+ order, `key=value` arguments, and repeatable `--param key=value` options:
139
+
140
+ ```bash
141
+ gezel do story-batch c23n limit=3 --wait --json
142
+ gezel task wait my-project/12 --timeout 7200 --json
143
+ gezel task resume my-project/12 --json
144
+ gezel task notes my-project/12 --warnings --json
145
+ ```
146
+
147
+ Only explicit values are sent; the service resolves defaults such as
148
+ `{{task.dir}}` after allocating the task. Waiting exits with 0 for completion,
149
+ 1 for cancellation, 2 for a paused task or pending user question, and 3 for a
150
+ timeout. A timeout leaves the daemon task running. Progress goes to stderr;
151
+ `--json` emits the result on stdout. `resume` retries a paused task using its
152
+ saved recipe. Answer pending questions in Gezel before waiting again.
153
+
154
+ For deterministic orchestration around several craftbooks, create
155
+ `.gezel/workflows/storyify.mjs`:
156
+
157
+ ```js
158
+ export async function run({ client, projectId, workspace, args, log, runCraftbook }) {
159
+ const [region] = args;
160
+ log(`Working on ${region} in ${workspace}`);
161
+ return runCraftbook('story-batch', { region });
162
+ }
163
+ ```
164
+
165
+ Run it with `gezel workflow storyify c23n --json`. The module receives the
166
+ public `GezelClient`, the directory's project id, its absolute workspace,
167
+ arguments, a stderr logger, and `runCraftbook(id, params, options)`. That helper
168
+ starts a **project** craftbook and waits; options include `timeoutMs`, a saved
169
+ `taskRef` to follow, `parentTaskRef` to link the child to its batch, and
170
+ `onCreated(task)` to checkpoint the new reference.
171
+ For drivers that generate craftbook documents, `validateCraftbook(document)`
172
+ checks the same schema and step contracts as the daemon and returns the runtime
173
+ craftbook. Call it before installing files or freezing a batch checkpoint;
174
+ invalid documents throw actionable authoring errors without creating a task.
175
+ Returning an object with `exitCode` sets the shell exit status. Module paths
176
+ also work: `gezel workflow ./pipeline/storyify.mjs c23n`.
177
+
178
+ To expose that driver as one command, add
179
+ `"cliWorkflow": { "module": ".gezel/workflows/storyify.mjs" }` to a project
180
+ craftbook and declare its inputs in `paramSchema`. Then run
181
+ `gezel do my-batch c23n limit=200 --json`. Its module receives `craftbook` and
182
+ validated explicit `params` in addition to the context above. The driver owns
183
+ parent creation, defaults, checkpoints, bounded child concurrency, and the
184
+ final result. Modules must resolve inside the project workspace. Only project
185
+ craftbooks can use this entry point; `--strict-sandbox` rejects it.
186
+
187
+ These drivers run in the foreground even without `--wait`; keep the terminal
188
+ open until completion. A timeout applies to each child wait. If the CLI exits,
189
+ already-created daemon tasks survive, but further orchestration requires the
190
+ workflow's resume command. `gezel task wait` observes a parent and its children;
191
+ it does not restart a repository driver.
192
+
193
+ Project recipes live in `.gezel/craftbooks/<id>/manifest.json` (identity) and
194
+ `versions/<version>/craftbook.json` (the complete recipe, including embedded
195
+ scripts). Legacy version manifests plus `scripts/*.ts` remain supported.
196
+ Changing a recipe affects new tasks; running tasks retain their snapshots.
197
+
198
+ CLI craftbook launches, including TUI `/do`, authorize the exact embedded
199
+ script contents in that task snapshot. On Windows and other platforms without
200
+ an enforceable OS network boundary, those scripts use best-effort network
201
+ isolation. Declared capabilities and project/security policies still apply.
202
+ Use `gezel do ... --strict-sandbox` to require the OS boundary instead. Edited
203
+ scripts do not inherit the old source's trust, and a model session cannot
204
+ grant trust. Workflow modules themselves run as ordinary local Node code,
205
+ with the invoking user's permissions, like an npm script.
206
+
92
207
  ## What you get with no further setup
93
208
 
94
209
  The CLI does not bundle model weights or native inference engines; those are
95
210
  downloaded only on demand when you opt into on-device models. Straight away
96
211
  you can use:
97
212
 
98
- - The interactive TUI (`gezel`) and one-shot prompts (`gezel run "…"`)
213
+ - The interactive TUI (`gezel`), which walks you through choosing a model on
214
+ first use, and one-shot prompts (`gezel run "…"`) once a model is set up.
215
+ Until then `run` downloads nothing: it names the setup commands and exits.
99
216
  - Cloud providers — OpenAI, Anthropic, GitHub Copilot, and any
100
217
  OpenAI-compatible endpoint
101
- - Gezel and project management (`gezel agent`, `gezel env`, `gezel task`)
218
+ - Gezel and project management (`gezel agent`, `gezel project`, `gezel task`)
102
219
  - Skills and handbook export (`gezel skills convert`, `gezel handboek export`) —
103
220
  these need no running daemon at all
104
221
 
@@ -145,11 +262,15 @@ Run `gezel --help` for the full list. The most-used ones:
145
262
  | `gezel` | Launch the interactive TUI |
146
263
  | `gezel run [prompt…]` | One-shot prompt in the current directory's project, using its voorman by default; optionally `--gezel <id>` / `--project <folder>` |
147
264
  | `gezel do <craftbook…>` | Start a craftbook as an immediately dispatched task in the current directory's project; accepts its id or display name |
265
+ | `gezel workflow <name-or-file> [args…]` | Run an explicitly trusted repository workflow from `.gezel/workflows/<name>.mjs` or a module path |
266
+ | `gezel secret list / set / remove` | Manage write-only provider credentials, including the Brave search key |
267
+ | `gezel task wait <ref>` / `resume <ref>` | Follow a task to completion, or retry a paused task and follow it |
268
+ | `gezel task notes <ref> --warnings` | Read task notes and runtime warnings from its recent sessions |
148
269
  | `gezel start` / `stop` / `status` | Use or inspect the selected service. `stop` is the same hard stop as the desktop UX: cancel work, unload local engines, and switch to Reactive. `stop --daemon` shuts down a user-owned daemon process itself. `start --web` serves the browser UI. On hosts without a Gezel machine service, a started daemon prefers the canonical port 6228 (ephemeral fallback) so third-party OpenAI clients get a stable `https://127.0.0.1:6228/v1` base URL; with a machine service installed, the service owns 6228 and started daemons use an ephemeral port (`--port` pins one explicitly). |
149
270
  | `gezel doctor` | Report on the local install |
150
271
  | `gezel mode [read-only\|reactive\|reactive+tasks\|full-play]` | Show or change how much AI activity is allowed |
151
272
  | `gezel agent list\|create\|show` | Manage your gezels |
152
- | `gezel env list\|create\|install` | Manage projects and their packages |
273
+ | `gezel project list\|create\|install` | Manage projects and their packages (`gezel env` is the same command) |
153
274
  | `gezel task list\|create\|show` | Manage tasks |
154
275
  | `gezel model list\|pull\|export` | Manage on-device chat models. `export <id> [file]` downloads the catalog model if needed, then writes a portable, checksum-verified `.gezmodel` you can move to another machine |
155
276
  | `gezel native install\|list\|status` | Manage native engine binaries |
@@ -286,6 +286,7 @@ import {
286
286
  createTrustingFetch,
287
287
  discoverOrSpawn,
288
288
  electronNativeBinCandidates,
289
+ ensureProjectForFolder as ensureClientProjectForFolder,
289
290
  isProcessAlive,
290
291
  readRuntime,
291
292
  readSystemServiceEndpoint,
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
 
3
3
  // src/app-command.ts
4
- import { readFile as readFile2 } from "fs/promises";
4
+ import { readFile as readFile2, realpath } from "fs/promises";
5
5
  import { isAbsolute, join as join2, resolve as resolve2 } from "path";
6
6
  import { compareSemver } from "@bendyline/gezel";
7
7
 
@@ -23,6 +23,7 @@ import {
23
23
  createTrustingFetch,
24
24
  discoverOrSpawn,
25
25
  electronNativeBinCandidates,
26
+ ensureProjectForFolder as ensureClientProjectForFolder,
26
27
  isProcessAlive,
27
28
  readRuntime,
28
29
  readSystemServiceEndpoint,
@@ -39,25 +40,15 @@ var CliError = class extends Error {
39
40
  };
40
41
  async function ensureProjectForFolder(client, folderPath) {
41
42
  const wd = resolve(folderPath);
42
- const eq = (a, b) => !!a && (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
43
- const { projects } = await client.listProjects();
44
- const exact = projects.find((p) => eq(p.workingDir, wd));
45
- if (exact) return exact.id;
46
43
  const name = basename(wd) || "workspace";
47
- const orphan = projects.find((p) => !p.workingDir && p.name === name);
48
- if (orphan) {
49
- await client.setProjectWorkingDir(orphan.id, wd);
50
- return orphan.id;
51
- }
52
- const created = await client.createProject({
53
- name,
44
+ const result = await ensureClientProjectForFolder(client, wd, {
45
+ mode: "solo",
46
+ source: "cli",
54
47
  description: `CLI workspace at ${wd}`,
55
48
  about: `${name} \u2014 working directory ${wd}. Fill in who this project is for, what's in scope, and what's explicitly out of scope.`,
56
- missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`,
57
- mode: "solo",
58
- workingDir: wd
49
+ missionObjectives: `${name} \u2014 fill in concrete success criteria for this project.`
59
50
  });
60
- return created.id;
51
+ return result.projectId;
61
52
  }
62
53
 
63
54
  // src/app-command.ts
@@ -306,11 +297,12 @@ async function runAppSetEnabled(client, appId, enabled) {
306
297
  throw new CliError(apiMessage(err));
307
298
  }
308
299
  }
309
- function findProjectForFolder(projects, folder) {
310
- const wd = resolve2(folder);
311
- return projects.find(
312
- (project) => !!project.workingDir && (process.platform === "win32" ? project.workingDir.toLowerCase() === wd.toLowerCase() : project.workingDir === wd)
313
- );
300
+ async function findProjectForFolder(projects, folder) {
301
+ const requested = resolve2(folder);
302
+ const real = await realpath(requested).catch(() => requested);
303
+ const fold = (p) => process.platform === "win32" || process.platform === "darwin" ? p.toLowerCase() : p;
304
+ const wanted = /* @__PURE__ */ new Set([fold(requested), fold(real)]);
305
+ return projects.find((project) => !!project.workingDir && wanted.has(fold(project.workingDir)));
314
306
  }
315
307
  function parseParamFlags(flags) {
316
308
  const params = {};
@@ -398,7 +390,7 @@ async function runAppApply(client, appId, folder, opts) {
398
390
  }
399
391
  const params = parseParamFlags(opts.param ?? []);
400
392
  const { projects } = await client.listProjects();
401
- const existing = findProjectForFolder(projects, folder);
393
+ const existing = await findProjectForFolder(projects, folder);
402
394
  const projectId = existing?.id ?? await ensureProjectForFolder(client, folder);
403
395
  const project = await client.getProject(projectId);
404
396
  if (!opts.json) {
@@ -453,7 +445,7 @@ async function runAppApply(client, appId, folder, opts) {
453
445
  }
454
446
  async function runAppStatus(client, folder, opts) {
455
447
  const { projects } = await client.listProjects();
456
- const project = findProjectForFolder(projects, folder);
448
+ const project = await findProjectForFolder(projects, folder);
457
449
  if (!project) {
458
450
  console.log(`No gezel project is linked to ${resolve2(folder)}.`);
459
451
  console.log("Apply an app here with: gezel app apply <appId>");
@@ -509,7 +501,7 @@ async function openUrlInBrowser(url) {
509
501
  async function resolveServeProject(client, appId, folder) {
510
502
  const { projects } = await client.listProjects();
511
503
  if (!appId) {
512
- const existing = findProjectForFolder(projects, folder);
504
+ const existing = await findProjectForFolder(projects, folder);
513
505
  const projectId = existing?.id ?? await ensureProjectForFolder(client, folder);
514
506
  const project = await client.getProject(projectId);
515
507
  if (!project.projectType) {