@north-light/cli 0.0.0-stage → 0.3.413

package/dist/commands/cron.js

@@ -0,0 +1,11 @@
+var W=Object.defineProperty;var o=(n,e)=>W(n,"name",{value:e,configurable:!0});import{envNodeId as N,envProfileId as U}from"../shared/env.js";import{existsSync as M,statSync as Y}from"node:fs";import{resolve as H}from"node:path";import{defineBranch as B,defineLeaf as h}from"../core/command.js";import{InputError as c,readStdinRaw as V}from"../core/io.js";import{parseWhen as z,parseCadence as Z,cadenceDisplay as k}from"../core/wake.js";import{profilesStateBlock as j,resolveProfileViaDaemon as J}from"./profile/daemon-profiles.js";import{cliClient as l,rethrowAsCliError as u}from"./api-client.js";async function L(n){return(await J(n.trim())).id}o(L,"canonicalProfileId");function b(n,e){return e!==void 0&&e.trim()!==""?{tz:e,now:n}:{now:n}}o(b,"parseOpts");function $(n){const e={wake_in_past:'Pick a future instant \u2014 a positive duration ("5m","2h") or an ISO time later than now.',bad_when:'Use a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").',bad_cadence:'Use a duration ("6h"), a 5-field cron ("0 9 * * *"), or an @alias ("@daily").',unknown_zone:'Pass --tz with an IANA zone name (e.g. "America/New_York").',cadence_too_fast:'Use a cadence of at least 60s (e.g. "1m","5m","1h").'};throw new c({error:n.code,message:n.message,received:n.received,next:e[n.code]??"Fix the time value and retry."})}o($,"throwTimeError");function G(n){const e=/^(\d+)(s|m|h)?$/.exec(n.trim());if(e===null)throw new c({error:"bad_run_timeout",message:`"${n}" is not a valid run timeout`,field:"run-timeout",next:'Use a duration like "90s", "5m", "1h", or bare seconds ("300").'});const r=Number(e[1]),t=e[2]==="h"?3600:e[2]==="m"?60:1,i=r*t;if(i<=0)throw new c({error:"bad_run_timeout",message:"run timeout must be positive",field:"run-timeout",next:'Use a positive duration, e.g. "5m".'});return i}o(G,"parseRunTimeout");function f(n){const e=n??U();return e!==void 0&&e.trim()!==""?{profile:e}:void 0}o(f,"scopeQuery");function Q(n){if(n===void 0)return process.cwd();const e=H(n);if(!M(e)||!Y(e).isDirectory())throw new c({error:"bad_cwd",message:`${e} is not a directory`,field:"cwd",next:"Pass --cwd with an existing directory, or omit it to inherit this one."});return e}o(Q,"resolveCwd");function X(n){const e=Array.isArray(n)?n.map(String):typeof n=="string"&&n!==""?[n]:[];if(e.length===0)return null;const r={};for(const t of e){const i=t.indexOf("="),s=i===-1?"":t.slice(0,i);if(!/^[A-Za-z_][A-Za-z0-9_]*$/.test(s))throw new c({error:"bad_env",message:`"${t}" is not KEY=VALUE`,field:"env",next:"Pass --env KEY=VALUE (repeat the flag per variable); KEY must be a shell-legal name."});r[s]=t.slice(i+1)}return JSON.stringify(r)}o(X,"resolveEnvJson");function p(n){const e=typeof n.cronId=="string"?n.cronId.trim():"";if(e==="")throw new c({error:"missing_cron_id",message:"a cron id is required",field:"cron-id",next:"Pass the cron id from `crtr cron list`."});return e}o(p,"requireCronId");function ee(n){if(n===null)return"never run";const e=n.finished??"",r=n.exit_code===0?"ok":n.exit_code===-1?"TIMEOUT":n.exit_code===null?"no exit":`exit ${n.exit_code}`;return e===""?r:`${r} ${e}`}o(ee,"healthDisplay");function ne(n){const e=n.exit_code===null?"no exit":n.exit_code===-1?"TIMEOUT":`exit ${n.exit_code}`,r=n.duration_ms!==null?`${n.duration_ms}ms`:"\u2014";return`- ${n.started} \u2014 ${e}, ${r} \u2014 ${n.delivered??"(no disposition recorded)"}`}o(ne,"renderRun");const te=h({name:"add",description:"arm a scheduled command (bash on stdin; one of --at / --every)",whenToUse:"you need to arm a new bash schedule, rather than inspect or control an existing cron.",help:{name:"cron add",summary:"arm a scheduled command",params:[{kind:"stdin",name:"command",required:!0,constraint:"Arbitrary bash the daemon runs at each fire. Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Runs via `bash -c` in this cwd with $CRTR_CRON_ID, $CRTR_CRON_NAME, and $CRTR_RUN_ID in the env ($CRTR_ANCHOR too when anchored). The scheduler does not interpret it as a node action; a bash predicate can decide whether this fire acts, not arm a native predicate trigger. A run that must branch on canvas state should call `crtr --json <cmd>` and read the leaf's declared outputs, rather than parsing the prose output."},{kind:"flag",name:"name",type:"string",required:!0,constraint:"Agent-legible label \u2014 how the cron shows in `cron list`."},{kind:"flag",name:"at",type:"string",required:!1,constraint:`One-shot: run the stored bash once at <when> \u2014 a duration ("90s","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", interpreted in --tz else host zone). Exactly one of --at / --every is required. The row is deleted after its run unless the run's disposition pauses it.`},{kind:"flag",name:"every",type:"string",required:!1,constraint:'Recurring: run the stored bash at each cadence \u2014 a fixed interval ("6h" \u2014 first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required. Use this for a bash condition that only the local filesystem knows: if it exits 75, the next cadence re-checks it. A host platform can also re-check it early by calling the daemon\'s `POST /v1/crons/poke` endpoint.'},{kind:"flag",name:"tz",type:"string",required:!1,constraint:'IANA zone (e.g. "America/New_York") for a bare-ISO --at or a calendar --every. Defaults to the host zone.'},{kind:"flag",name:"on-output",type:"enum",choices:["silent","on-failure","always","on-change"],required:!1,constraint:"What each run does with its output. Defaults to on-change for a node:<id> sink; otherwise on-failure. silent: record in the run log, tell nobody \u2014 never escalate. on-failure: no success delivery; a failing run pauses the cron and spawns a node to deal with it. always: deliver stdout every run to --sink at --tier. on-change: deliver stdout only when it differs from the previous run's \u2014 the shape polling wants."},{kind:"flag",name:"sink",type:"string",required:!1,constraint:`Where always/on-change stdout deliveries go: "node:<id>" (an existing node's inbox \u2014 must exist now; gone/finalized at fire time is a failure), "spawn:<kind>" (each delivered output creates a self-finishing node with stdout as kickoff \u2014 a managed child while its creator exists, otherwise a terminal parentless root), or "human" (the humanloop inbox). Required by always/on-change, rejected otherwise.`},{kind:"flag",name:"tier",type:"enum",choices:["normal","urgent","critical"],required:!1,default:"urgent",constraint:"Inbox priority of a node-sink delivery. urgent (default): steers the target mid-turn, or wakes it when dormant \u2014 a fire is news the node asked for on a schedule, so it should land now. normal: waits for the running turn to settle. critical: aborts the running turn outright."},{kind:"flag",name:"expires",type:"string",required:!1,constraint:"Clock bound (same grammar as --at): the row is deleted once this instant passes. The self-limiting half of a poll-until pattern. For a held one-shot (last run exited 75), expiry bounds the wait for eligibility \u2014 the row is deleted UNFIRED, never fired blind at expiry."},{kind:"flag",name:"anchor",type:"string",required:!1,constraint:"Couple the cron's lifetime to a node: the row is deleted when that node is deleted. Without an anchor it outlives every node; it ends through its one-shot run, --expires, explicit cancellation, or self-cancellation from its bash."},{kind:"flag",name:"anchor-self",type:"bool",required:!1,constraint:"Anchor to the calling node ($CRTR_NODE_ID). Errors outside a node."},{kind:"flag",name:"cancel-on-wake",type:"bool",required:!1,constraint:"Also delete the row when the anchor node revives: use only when the cron belongs to that current dormancy, not for standing work. Requires an anchor; at most one cancel-on-wake cron per anchor \u2014 arming a second replaces the anchor\u2019s pending one."},{kind:"flag",name:"run-timeout",type:"string",required:!1,default:"5m",constraint:'Kill a run that exceeds this ("90s","5m","1h", or bare seconds). A timeout is a failure.'},{kind:"flag",name:"overlap",type:"enum",choices:["skip","queue","replace"],required:!1,default:"skip",constraint:"A fire landing while the previous run is still going. skip (default): log the skip, do not start a second run. queue: run once more after the current finishes (depth 1; further fires collapse). replace: kill the running instance and start fresh."},{kind:"flag",name:"cwd",type:"path",required:!1,constraint:"Directory every run executes in. Defaults to this one, must exist now, and is snapshotted onto the row \u2014 a cron never re-resolves its context. In a hosted runtime, runs are sandboxed and see only the app's own folders: an omitted --cwd that is outside them becomes the node's directory or the app files directory, and an explicit --cwd outside them is refused now (`cron show` prints the directory the row got)."},{kind:"flag",name:"env",type:"string",required:!1,repeatable:!0,constraint:"KEY=VALUE added to every run's env (repeat per variable). Snapshotted at arm time; overlays the operational env, alongside $CRTR_CRON_ID/$CRTR_CRON_NAME/$CRTR_RUN_ID."},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Profile the runs resolve config and credentials under, and \u2014 under --scope profile \u2014 the profile this cron lists and cancels within. A profile id or manifest name from the <profiles> list below; a close-enough name resolves to the nearest profile. Defaults to the calling node's ($CRTR_PROFILE_ID)."},{kind:"flag",name:"scope",type:"enum",choices:["profile","global"],required:!1,constraint:"Who lists and cancels this cron: profile (default when a profile is resolved) confines it to that profile; global makes it canvas-home-wide, visible from every profile."}],output:[{name:"cron_id",type:"string",required:!0,constraint:"The server-minted armed cron id \u2014 inspect with `cron show <cron_id>`, cancel with `cron cancel <cron_id>`."},{name:"fire_at",type:"string",required:!0,constraint:"Next fire (UTC ISO)."},{name:"recur",type:"string",required:!0,constraint:'Cadence display; "none" for a one-shot.'}],outputKind:"object",effects:["Arms one cron row (daemon-run; survives this process and every node).","Each fire runs the command via bash in this cwd and records a run-log entry.","A failing run (nonzero exit, timeout, undeliverable sink) pauses the cron and spawns a node to deal with it \u2014 unless --on-output silent."]},helpState:{leaf:j},run:o(async n=>{let e=typeof n.command=="string"?n.command.trim():"";if(e===""&&(e=(await V()).trim()),e==="")throw new c({error:"missing_command",message:"no command on stdin",field:"command",next:"Pipe the bash command on stdin (e.g. from a single-quoted heredoc)."});const r=typeof n.name=="string"?n.name.trim():"";if(r==="")throw new c({error:"missing_name",message:"--name is required",field:"name",next:"Pass --name <label>."});const t=typeof n.at=="string"&&n.at!==""?n.at:void 0,i=typeof n.every=="string"&&n.every!==""?n.every:void 0;if(t===void 0==(i===void 0))throw new c({error:"bad_schedule",message:t===void 0?"one of --at / --every is required":"--at and --every are mutually exclusive",next:"Pass exactly one: --at <when> for a one-shot, or --every <cadence> for a recurrence."});const s=typeof n.tz=="string"&&n.tz!==""?n.tz:void 0,m=new Date;let d,T=null;if(i!==void 0){const a=Z(i,b(m,s));"error"in a&&$(a.error),d=a.firstFireAt,T=a.recur}else{const a=z(t,b(m,s));"error"in a&&$(a.error),d=a.fireAt}let C=null;const R=typeof n.expires=="string"&&n.expires!==""?n.expires:void 0;if(R!==void 0){const a=z(R,b(m,s));"error"in a&&$(a.error),C=a.fireAt}const q=typeof n.anchor=="string"&&n.anchor!==""?n.anchor:void 0,A=n.anchorSelf===!0;if(q!==void 0&&A)throw new c({error:"bad_anchor",message:"--anchor and --anchor-self are mutually exclusive",next:"Pass one anchor or the other."});let w=q??null;if(A){const a=N();if(a===void 0||a==="")throw new c({error:"no_self_node",message:"--anchor-self requires a calling node ($CRTR_NODE_ID is unset)",next:"Run from inside a node, or pass --anchor <node-id> explicitly."});w=a}const I=n.cancelOnWake===!0;if(I&&w===null)throw new c({error:"cancel_on_wake_needs_anchor",message:"--cancel-on-wake requires an anchor",next:"Add --anchor <node-id> or --anchor-self."});const O=typeof n.runTimeout=="string"&&n.runTimeout!==""?G(n.runTimeout):void 0,S=typeof n.cwd=="string"&&n.cwd!==""?n.cwd:void 0,g=N(),E=g?await l().getNode(g).catch(u):null,K=Q(S??(E?.isolated?E.cwd:void 0)),F=X(n.env),D=typeof n.profile=="string"&&n.profile!==""?n.profile:void 0,y=U(),_=D!==void 0?await L(D):y!==void 0&&y.trim()!==""?y:void 0,P=n.scope??(_!==void 0?"profile":"global");if(P==="profile"&&_===void 0)throw new c({error:"scope_needs_profile",message:"--scope profile names the profile this cron lists and cancels within, but no profile is resolved",field:"profile",next:"Pass --profile <id>, or use --scope global for a canvas-home-wide cron."});const v=g,x=await l().armCron({name:r,command:e,fire_at:d,recur:T,tz:s??null,created_by:v!==void 0&&v!==""?v:null,cwd:K,...S===void 0?{cwd_is_default:!0}:{},env_json:F,profile:_??null,scope:P,on_output:n.onOutput,sink:typeof n.sink=="string"&&n.sink!==""?n.sink:null,tier:n.tier??"urgent",expires_at:C,anchor_node:w,cancel_on_wake:I,...O!==void 0?{run_timeout_s:O}:{},overlap:n.overlap??"skip"}).catch(u);return{cron_id:x.cron_id,fire_at:x.fire_at,recur:k(x.recur)}},"run"),render:o(n=>{const e=String(n.recur),r=e==="none"?"one-shot (row deleted after the run)":e;return`Cron armed \u2014 ${String(n.cron_id)}.
+
+- next fire: ${String(n.fire_at)}
+- cadence: ${r}
+
+It runs daemon-side; nothing more to do here. Inspect it with \`crtr cron show ${String(n.cron_id)}\`; cancel with \`crtr cron cancel ${String(n.cron_id)}\` from its profile, or pass \`--profile <profile>\` from another profile.`},"render")}),re=h({name:"list",description:"what is scheduled, with next fire and recent health",whenToUse:"you want to see every cron in scope \u2014 to find an id to show/cancel, to check what fires next and what is paused, or to spot one whose last run failed.",help:{name:"cron list",summary:"every cron in scope, next-fire order",params:[],output:[{name:"crons",type:"object[]",required:!0,constraint:"One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), held (true after an exit-75 gate; a recurring row re-checks at fire_at or when a host platform calls `POST /v1/crons/poke`, while a one-shot needs that call or `crtr cron run <cron-id>`), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered \u2014 null if it never ran)."}],outputKind:"object",effects:["None. Read-only."]},run:o(async()=>({crons:(await l().listCrons(f()).catch(u)).map(e=>({cron_id:e.cron_id,name:e.name,fire_at:e.fire_at,recur:k(e.recur),state:e.state,held:e.held,on_output:e.on_output,sink:e.sink,expires_at:e.expires_at,last_run:e.last_run}))}),"run"),render:o(n=>{const e=n.crons;if(e.length===0)return"No crons armed.";const r=e.map(t=>{const i=[`next ${t.fire_at}`,t.recur==="none"?"one-shot":t.recur,t.sink!==null?`${t.on_output} \u2192 ${t.sink}`:t.on_output,`last: ${ee(t.last_run)}`];t.expires_at!==null&&i.push(`expires ${t.expires_at}`);const s=t.state==="paused"?t.held?" [PAUSED (held) \u2014 resume or cancel]":" [PAUSED \u2014 resume or cancel]":t.held?t.recur==="none"?` [HELD \u2014 last run exited 75; run manually with \`crtr cron run ${t.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`]`:" [HELD \u2014 last run exited 75; re-checks at the next cadence or when a host platform calls `POST /v1/crons/poke`]":"";return`- ${t.name} (${t.cron_id}) \u2014 ${i.join(", ")}${s}`});return`${e.length} cron(s):
+
+${r.join(`
+`)}`},"render")}),oe=h({name:"show",description:"one cron: full config plus its run history",whenToUse:'you want to inspect one cron \u2014 its exact command and settings, and what its recent runs actually did (exit codes, output heads, where deliveries went). The run log is how you answer "did it silently stop working".',help:{name:"cron show",summary:"one cron with its run-log ring",params:[{kind:"positional",name:"cron-id",required:!0,constraint:"The cron to inspect (from `cron list`)."}],output:[{name:"cron",type:"object",required:!0,constraint:"The full cron config: command, schedule, snapshotted context (cwd, profile, scope, env var names \u2014 values stay server-side), disposition, sink, coupling, state."},{name:"runs",type:"object[]",required:!0,constraint:"The bounded run log, most recent first: started, exit_code (-1 = timeout kill), duration_ms, stdout/stderr heads, delivered (what the sink did, or why it did not)."}],outputKind:"object",effects:["None. Read-only."]},run:o(async n=>{const e=p(n),r=await l().showCron(e,f()).catch(t=>u(t,"Check the id against `crtr cron list`."));return{cron:r.cron,runs:r.runs}},"run"),render:o(n=>{const e=n.cron,r=n.runs,t=e.recur!==null?k(e.recur):e.held?"one-shot":`one-shot at ${e.fire_at}`,i=e.tz!==null?` (tz ${e.tz})`:"",s=e.held?e.recur!==null?`- schedule: ${t}${i} \u2014 next re-check ${e.fire_at} (held \u2014 also re-checks when a host platform calls \`POST /v1/crons/poke\`; last run exited 75)`:e.expires_at!==null?`- schedule: ${t}${i} \u2014 no scheduled re-check \u2014 expires ${e.expires_at} (held \u2014 run manually with \`crtr cron run ${e.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`; deleted unfired at expiry)`:`- schedule: ${t}${i} \u2014 no scheduled re-check (held \u2014 run manually with \`crtr cron run ${e.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`)`:`- schedule: ${t}${i} \u2014 next fire ${e.fire_at}`,m=e.state==="paused"?e.held?" \u2014 PAUSED (held)":" \u2014 PAUSED":e.held?" \u2014 HELD":"",d=[`# ${e.name} (${e.cron_id})${m}`,"",s,`- disposition: ${e.on_output}${e.sink!==null?` \u2192 ${e.sink} (tier ${e.tier})`:""}`,`- context: cwd ${e.cwd}${e.profile!==null?`, profile ${e.profile}`:""}, scope ${e.scope}${e.env_keys.length>0?`, env ${e.env_keys.join(", ")}`:""}`,`- run: timeout ${e.run_timeout_s}s, overlap ${e.overlap}${e.run_state==="running"?" \u2014 a run is IN FLIGHT now":""}`];return e.expires_at!==null&&d.push(`- expires: ${e.expires_at}`),e.anchor_node!==null&&d.push(`- anchored to node ${e.anchor_node}${e.cancel_on_wake?" (canceled when it wakes)":""}`),e.created_by!==null&&d.push(`- created by node ${e.created_by}`),d.push("","## Command","","```bash",e.command,"```","",`## Runs (most recent first, last ${r.length})`,""),d.push(...r.length>0?r.map(ne):["(no runs yet)"]),d.join(`
+`)},"render")}),ie=h({name:"run",description:"execute now, out of band \u2014 does not advance the schedule",whenToUse:"you need the stored command to execute now because its own behavior has not been exercised, or you fixed the command behind a paused cron. This is not a scheduled-delivery check: once `cron add` has armed a valid row, trust the clock and node delivery rather than firing it again for reassurance.",help:{name:"cron run",summary:"fire one cron now, out of band, and report the settled run",params:[{kind:"positional",name:"cron-id",required:!0,constraint:"The cron to run (from `cron list`)."}],output:[{name:"exit_code",type:"number",required:!1,constraint:"The run's exit code (-1 = timeout kill; null when the process failed to start)."},{name:"duration_ms",type:"number",required:!0,constraint:"Wall-clock run time."},{name:"stdout_head",type:"string",required:!1,constraint:"Captured stdout (head)."},{name:"stderr_head",type:"string",required:!1,constraint:"Captured stderr (head)."},{name:"delivered",type:"string",required:!0,constraint:"What the sink did with the output, or why it did not."}],outputKind:"object",effects:["Runs the command NOW (blocking this call until it settles) and records the run in the cron's run log.","Delivers per the cron's disposition; never advances the schedule, consumes a one-shot, or escalates a failure."]},run:o(async n=>{const e=p(n),r=await l().showCron(e,f()).catch(s=>u(s,"Check the id against `crtr cron list`."));return await l({timeoutMs:r.cron.run_timeout_s*1e3+15e3}).runCron(e,f()).catch(s=>u(s))},"run"),render:o(n=>{const e=n,t=[`Run settled \u2014 exit ${e.exit_code===null?"no exit (process error)":e.exit_code===-1?"-1 (TIMEOUT)":String(e.exit_code)}, ${e.duration_ms??"?"}ms.`,"",`- delivered: ${e.delivered??"(nothing recorded)"}`];return e.stdout_head!==null&&t.push("","## stdout (head)","",e.stdout_head),e.stderr_head!==null&&t.push("","## stderr (head)","",e.stderr_head),t.join(`
+`)},"render")}),ae=h({name:"pause",description:"stop firing without losing config or history",whenToUse:"a cron should stop firing for now but its config and run history are worth keeping \u2014 a job under investigation, or a poll to silence temporarily. (A failing cron pauses itself.)",help:{name:"cron pause",summary:"pause one cron",params:[{kind:"positional",name:"cron-id",required:!0,constraint:"The cron to pause (from `cron list`)."}],output:[],outputKind:"object",effects:["Stops the cron firing until `cron resume`. An in-flight run settles normally; the row just stops being due."]},run:o(async n=>{const e=p(n);return await l().pauseCron(e,f()).catch(r=>u(r,"Check the id against `crtr cron list`.")),{}},"run"),render:o(()=>"Cron paused.","render")}),se=h({name:"resume",description:"re-arm a paused cron",whenToUse:"a paused cron should fire again \u2014 you fixed what made it fail (verify first with `cron run`), or its silence is over. A fire that came due while paused fires immediately on resume.",help:{name:"cron resume",summary:"resume one paused cron",params:[{kind:"positional",name:"cron-id",required:!0,constraint:"The cron to resume (from `cron list`)."}],output:[{name:"fire_at",type:"string",required:!0,constraint:"Next fire \u2014 if already past, it fires on the next daemon tick."}],outputKind:"object",effects:["Re-arms the cron. A past-due fire_at fires immediately (instant verification after un-wedging); a recurrence then advances naturally."]},run:o(async n=>{const e=p(n);return{fire_at:(await l().resumeCron(e,f()).catch(t=>u(t,"Check the id against `crtr cron list`."))).fire_at}},"run"),render:o(n=>`Cron resumed \u2014 next fire ${String(n.fire_at)} (if that is already past, it fires on the next tick).`,"render")}),ce=h({name:"cancel",description:"remove one cron (idempotent)",whenToUse:"a scheduled command should stop firing \u2014 it is obsolete, wrong, or its purpose is served. Idempotent, so a script can safely self-cancel with `crtr cron cancel $CRTR_CRON_ID` even if a racing cancel got there first.",help:{name:"cron cancel",summary:"remove one cron",params:[{kind:"positional",name:"cron-id",required:!0,constraint:"The cron to remove (from `cron list`, or $CRTR_CRON_ID inside a run)."},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Profile scope to cancel within. Defaults to the calling node's profile; pass the profile id or manifest name for a cron armed under another profile."}],output:[],outputKind:"object",effects:["Deletes the cron row and its run history; kills any in-flight run. A no-op if already gone."]},helpState:{leaf:j},run:o(async n=>{const e=p(n),r=process.env.CRTR_RUN_ID;return await l().cancelCron(e,{...f(typeof n.profile=="string"&&n.profile.trim()!==""?await L(n.profile):void 0),...r===void 0||r===""?{}:{run_id:r}}).catch(t=>u(t,"Check the id against `crtr cron list`.")),{}},"run"),render:o(()=>"Cron canceled.","render")});function _e(){return B({name:"cron",rootEntry:{concept:"one scheduling primitive \u2014 run this bash command, then",desc:"arm, inspect, and control scheduled bash commands the daemon runs on the clock",useWhen:"bash must run later or on a cadence, rather than waiting for a runtime-delivered wake."},help:{name:"cron",summary:"scheduled bash commands, daemon-run",model:"A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node (its disposition defaults to on-change), an existing node's lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent \u2014 right when the recurrence is your polling cadence. Exit 75 holds the row. A held recurring row re-checks at its next natural slot, or when a host platform calls the daemon's `POST /v1/crons/poke` endpoint. A held one-shot has no scheduled re-check: it stays held until that endpoint is called, or you execute its bash explicitly with `crtr cron run <cron-id>` (which does not unhold or reschedule the row). A local filesystem condition does not call the daemon, so use --every for that condition or run the cron explicitly after it changes. Any other nonzero exit is a real failure and escalates per --on-output. Keep gate errors nonzero so a broken probe is loud instead of silently held. Beyond the exit-code contract, cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run's disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it."},children:[te,re,oe,ie,ae,se,ce]})}o(_e,"registerCron");export{_e as registerCron};

package/dist/commands/custom-object/ack.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const ackLeaf: LeafDef;

package/dist/commands/custom-object/ack.js

@@ -0,0 +1,3 @@
+var o=Object.defineProperty;var t=(e,r)=>o(e,"name",{value:r,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{routes as a}from"../../api/routes.js";import{cliClient as s,rethrowAsCliError as d}from"../api-client.js";import{OBJECT_REF as c,publishToken as u}from"./shared.js";const y=i({name:"ack",description:"acknowledge queue deliveries",whenToUse:"you have finished handling delivery ids from custom-object receive; acknowledge them so reconnect does not replay them.",help:{name:"custom-object ack",summary:"settle handled deliveries from a custom object queue",params:[{kind:"positional",name:"ref",required:!0,constraint:c},{kind:"flag",name:"delivery-id",type:"string",required:!0,repeatable:!0,constraint:"Delivery id from receive; repeat this flag to settle several ids together."},{kind:"flag",name:"token",type:"string",required:!1,sensitive:!0,constraint:"Object publish token; overrides CRTR_PUBLISH_TOKEN. Omit to use owner authority."}],output:[{name:"acknowledged",type:"number",required:!0,constraint:"Number settled."},{name:"unknown",type:"string[]",required:!1,constraint:"Ids not found or not pending, if any."}],outputKind:"object",effects:["Acknowledged deliveries are not replayed by receive."]},run:t(async e=>{const r={delivery_ids:e.deliveryId};try{return{...await s().request("POST",a.customObjectAck(e.ref),r,u(e))}}catch(n){d(n)}},"run"),render:t(e=>`<acknowledged count="${e.acknowledged}">${Array.isArray(e.unknown)&&e.unknown.length?`
+unknown: ${e.unknown.join(", ")}
+`:""}</acknowledged>`,"render")});export{y as ackLeaf};

package/dist/commands/custom-object/publish.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const publishLeaf: LeafDef;

package/dist/commands/custom-object/publish.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var r=(e,t)=>n(e,"name",{value:t,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{routes as o}from"../../api/routes.js";import{cliClient as u,rethrowAsCliError as d}from"../api-client.js";import{jsonValue as c,OBJECT_REF as l,publishToken as m}from"./shared.js";const g=i({name:"publish",description:"publish one declared event from a custom object",whenToUse:"your service or script has new state to announce to canvas watchers; inside an argv receiver this automatically attributes the event to its delivery.",help:{name:"custom-object publish",summary:"publish a declared event with a readable summary and optional state",params:[{kind:"positional",name:"ref",required:!0,constraint:l},{kind:"flag",name:"event",type:"string",required:!0,constraint:"Local event name declared at registration; the canvas publishes `<kind>.<event>` at its fixed level."},{kind:"flag",name:"summary",type:"string",required:!0,constraint:"Prose shown in the object and watchers\u2019 inboxes."},{kind:"flag",name:"state",type:"string",required:!1,constraint:"JSON value stored as the object\u2019s current state."},{kind:"flag",name:"cause",type:"string",required:!1,constraint:"Use the received line\u2019s message_id when reacting to a queue delivery (not delivery_id or seq). Inherits CRTR_CAUSE_EVENT in argv receivers; explicit --cause overrides it."},{kind:"flag",name:"token",type:"string",required:!1,sensitive:!0,constraint:"Publish token returned at registration; overrides CRTR_PUBLISH_TOKEN. Omit to use owner authority."}],output:[{name:"message_id",type:"string | null",required:!0,constraint:"Published event id (null when no message was stored)."},{name:"delivered",type:"number",required:!0,constraint:"Number of deliveries queued."},{name:"depth",type:"number",required:!0,constraint:"Cause-chain depth; more than 8 is rejected."}],outputKind:"object",effects:["Stores the summary and state and publishes the event to eligible watchers."]},run:r(async e=>{const t=e.cause??process.env.CRTR_CAUSE_EVENT,s={event:e.event,summary:e.summary,...e.state!==void 0?{state:c("state",e.state)}:{},...t?{cause:t}:{}};try{return{...await u().request("POST",o.customObjectEvents(e.ref),s,m(e))}}catch(a){d(a)}},"run"),render:r(e=>`<published message_id="${e.message_id}" delivered="${e.delivered}" depth="${e.depth}">`,"render")});export{g as publishLeaf};

package/dist/commands/custom-object/receive.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const receiveLeaf: LeafDef;

package/dist/commands/custom-object/receive.js

@@ -0,0 +1,2 @@
+var u=Object.defineProperty;var s=(n,t)=>u(n,"name",{value:t,configurable:!0});import{defineLeaf as f}from"../../core/command.js";import{APIError as m}from"../../api/errors.js";import{defaultSocketPath as p,socketFetch as h}from"../../api/node-transport.js";import{routes as y}from"../../api/routes.js";import{emitLine as v}from"../../core/io.js";import{usage as g}from"../../core/errors.js";import{cliClient as k,rethrowAsCliError as b}from"../api-client.js";import{OBJECT_REF as w,publishToken as O}from"./shared.js";const J=f({name:"receive",description:"stream queued events as JSONL",whenToUse:"your custom object has a queue receiver and your process needs to handle watched events; reconnect to replay all unacknowledged deliveries.",help:{name:"custom-object receive",summary:"follow the pending delivery queue, one JSON object per line",params:[{kind:"positional",name:"ref",required:!0,constraint:w},{kind:"flag",name:"after",type:"int",required:!1,constraint:"Legacy nonnegative sequence cursor; accepted but does not filter pending deliveries. Omit on reconnect; ack processed delivery_ids instead."},{kind:"flag",name:"token",type:"string",required:!1,sensitive:!0,constraint:"Object publish token; overrides CRTR_PUBLISH_TOKEN. Omit to use owner authority."}],output:[{name:"delivery",type:"QueueLineDTO",required:!1,constraint:"One JSONL record per pending delivery: delivery_id for ack, message_id for publish --cause, seq for ordering, event, level, object, actor, attrs, depth, created_at (optional summary, state, pointer). Reconnect replays all pending work; blank heartbeats are skipped."}],outputKind:"jsonl",effects:["None. Read-only; use ack after processing to settle each delivery."]},run:s(async n=>{const t=n.after??0;if(!Number.isSafeInteger(t)||t<0)throw g("--after must be a nonnegative safe integer",{field:"after",received:t,next:"Omit --after and acknowledge processed delivery ids."});try{await k().healthz();const a=`http://localhost${y.customObjectDeliveries(n.ref)}?after=${t}`,o=await h(p())(a,{headers:O(n)?.headers});if(!o.ok){const e=await o.json();throw new m(o.status,e.error?.code??"invalid_response",e.error?.message??`request failed with status ${o.status}`,e.error?.details)}if(!o.body)return;const d=o.body.getReader(),c=new TextDecoder;let r="";const l=s(e=>{e.trim()&&v({...JSON.parse(e)})},"line");try{for(;;){const e=await d.read();if(e.done)break;r+=c.decode(e.value,{stream:!0});let i;for(;(i=r.indexOf(`
+`))>=0;)l(r.slice(0,i)),r=r.slice(i+1)}r+=c.decode(),l(r)}finally{d.releaseLock()}}catch(a){b(a)}},"run")});export{J as receiveLeaf};

package/dist/commands/custom-object/register.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const registerLeaf: LeafDef;

package/dist/commands/custom-object/register.js

@@ -0,0 +1,3 @@
+var v=Object.defineProperty;var c=(e,r)=>v(e,"name",{value:r,configurable:!0});import{defineLeaf as m}from"../../core/command.js";import{usage as d}from"../../core/errors.js";import{routes as p}from"../../api/routes.js";import{cliClient as f,rethrowAsCliError as h}from"../api-client.js";import{jsonValue as u}from"./shared.js";const O=m({name:"register",description:"register or re-register a custom canvas object",whenToUse:"you have an external service, script or app whose declared events should be visible and watchable on the canvas; use this again to change its catalog or receiver, or rotate its token.",help:{name:"custom-object register",summary:"register or replace a named custom object\u2019s catalog and receiver",params:[{kind:"flag",name:"kind",type:"string",required:!0,constraint:"Dotted event namespace, not a built-in or reserved prefix; events are published as `<kind>.<local event>`."},{kind:"flag",name:"name",type:"string",required:!0,constraint:"Object name unique under its owner and kind."},{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Owner ref (repo, app, person or profile); omitted owner resolves from your current principal."},{kind:"flag",name:"description",type:"string",required:!0,constraint:"Human-readable description of the object."},{kind:"flag",name:"events",type:"string",required:!0,constraint:'JSON object of up to 64 local event names to `{ "level": 1..10, "supersedes"?: boolean }` declarations. These levels cap publishes.'},{kind:"flag",name:"receiver",type:"enum",choices:["queue","url","argv"],required:!1,constraint:"How this object receives watched events. Omit when it will only publish. On re-registration, omission removes the previous receiver and cancels its pending deliveries. Queue is pulled with receive and ack."},{kind:"flag",name:"url",type:"string",required:!1,constraint:"HTTPS receiver URL resolving only to public IP addresses; required exactly when --receiver url. Redirects are not followed."},{kind:"flag",name:"argv",type:"string",required:!1,constraint:"JSON array of nonempty command and arguments; required exactly when --receiver argv. Only a person or node can register an argv receiver."},{kind:"flag",name:"cwd",type:"path",required:!1,constraint:"Absolute working directory for argv; required exactly when --receiver argv."},{kind:"flag",name:"rotate-token",type:"bool",required:!1,constraint:"Issue a replacement publish token; invalidates the previous one. Save the returned token now; it is not shown again."}],output:[{name:"id",type:"string",required:!0,constraint:"Canvas object id."},{name:"name",type:"string",required:!0,constraint:"Resolved object name."},{name:"token",type:"string",required:!1,constraint:"New publish token on creation or rotation only; store securely for callers without owner authority."}],outputKind:"object",effects:["Creates or updates the object and its catalog. Changes publish a configured event; a rotation invalidates its prior token."]},run:c(async e=>{const r=e.receiver,s=e.url,a=e.argv,i=e.cwd;if((r==="url"?s===void 0||a!==void 0||i!==void 0:s!==void 0)||(r==="argv"?a===void 0||i===void 0:a!==void 0||i!==void 0))throw d("receiver flags must match: url needs --url; argv needs --argv and --cwd; queue needs neither",{field:"receiver",next:"Run `crtr custom-object register -h` and supply one receiver shape."});let n;if(r==="queue")n="queue";else if(r==="url")n={url:s};else if(r==="argv"){const t=u("argv",a);if(!Array.isArray(t)||t.length<1||!t.every(l=>typeof l=="string"&&l.length>0))throw d("--argv must be a nonempty JSON array of nonempty strings",{field:"argv",next:"Run `crtr custom-object register -h` for the receiver shape."});n={argv:t,cwd:i}}const o=u("events",e.events);if(o===null||typeof o!="object"||Array.isArray(o))throw d("--events must be a JSON object mapping local event names to declarations",{field:"events",next:"Run `crtr custom-object register -h` for the catalog shape."});const g={kind:e.kind,name:e.name,description:e.description,events:o,...e.owner?{owner:e.owner}:{},...n?{receiver:n}:{},...e.rotateToken?{rotate_token:!0}:{}};try{return{...await f().request("POST",p.customObjects(),g)}}catch(t){h(t)}},"run"),render:c(e=>`<registered id="${e.id}" name="${e.name}">${e.token?`
+token: ${e.token}
+`:""}</registered>`,"render")});export{O as registerLeaf};

package/dist/commands/custom-object/shared.d.ts

@@ -0,0 +1,5 @@
+export declare const OBJECT_REF = "Custom object id or name as resolved by the canvas; use the id returned by register when names are ambiguous.";
+export declare function jsonValue(flag: string, raw: unknown): unknown;
+export declare function publishToken(input: Record<string, unknown>): {
+    headers: Record<string, string>;
+} | undefined;

package/dist/commands/custom-object/shared.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var r=(e,t)=>o(e,"name",{value:t,configurable:!0});import{usage as n}from"../../core/errors.js";const i="Custom object id or name as resolved by the canvas; use the id returned by register when names are ambiguous.";function a(e,t){try{return JSON.parse(t)}catch{throw n(`--${e} must be valid JSON`,{field:e,received:t,next:`Run \`crtr custom-object ${e==="events"?"register":"publish"} -h\` for its shape.`})}}r(a,"jsonValue");function c(e){const t=e.token??process.env.CRTR_PUBLISH_TOKEN;return t?{headers:{authorization:`Bearer ${t}`}}:void 0}r(c,"publishToken");export{i as OBJECT_REF,a as jsonValue,c as publishToken};

package/dist/commands/custom-object/unregister.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const unregisterLeaf: LeafDef;

package/dist/commands/custom-object/unregister.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var t=(e,r)=>s(e,"name",{value:r,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{routes as o}from"../../api/routes.js";import{cliClient as n,rethrowAsCliError as a}from"../api-client.js";import{OBJECT_REF as c,publishToken as u}from"./shared.js";const h=i({name:"unregister",description:"remove a custom canvas object",whenToUse:"the registered service or script is retired and its event catalog, queue and watches should no longer exist.",help:{name:"custom-object unregister",summary:"delete the custom object and close its receiver",params:[{kind:"positional",name:"ref",required:!0,constraint:c},{kind:"flag",name:"token",type:"string",required:!1,sensitive:!0,constraint:"Object publish token; overrides CRTR_PUBLISH_TOKEN. Omit to use owner authority. An argv receiver requires a person or node principal."}],output:[],outputKind:"object",effects:["Publishes deleted, cancels pending deliveries, closes the stream and removes the object."]},run:t(async e=>{try{return await n().request("DELETE",o.customObject(e.ref),void 0,u(e)),{}}catch(r){a(r)}},"run"),render:t(()=>"<unregistered />","render")});export{h as unregisterLeaf};

package/dist/commands/custom-object.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerCustomObject(): BranchDef;

package/dist/commands/custom-object.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var e=(t,r)=>a(t,"name",{value:r,configurable:!0});import{defineBranch as s}from"../core/command.js";import{registerLeaf as c}from"./custom-object/register.js";import{publishLeaf as o}from"./custom-object/publish.js";import{receiveLeaf as n}from"./custom-object/receive.js";import{ackLeaf as i}from"./custom-object/ack.js";import{unregisterLeaf as m}from"./custom-object/unregister.js";function b(){return s({name:"custom-object",rootEntry:{concept:"an externally registered canvas object with declared events and an optional queue, URL or argv receiver",desc:"register, publish, receive, acknowledge and unregister custom objects",useWhen:"a service or script must publish state into the canvas or handle events from watched objects"},help:{name:"custom-object",summary:"register and operate custom canvas objects",model:"A registered object declares its event catalog and fixed levels. Publish updates its state and delivers events to watchers. A queue receiver consumes watched events via receive and ack; URL and argv receivers receive pushes. Use `crtr canvas watch --as` to make the object watch another canvas object."},children:[c,o,n,i,m]})}e(b,"registerCustomObject");export{b as registerCustomObject};

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const dashboardLeaf: LeafDef;

package/dist/commands/dashboard.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var u=(s,e)=>l(s,"name",{value:e,configurable:!0});import{defineLeaf as h}from"../core/command.js";import{InputError as m}from"../core/io.js";import{cliCanvasSource as w}from"./api-client.js";import{renderTreeFromSource as f,renderForestFromSource as p,dashboardRowsFromSource as b,dashboardRowsAllFromSource as S,enrichRowsFromSource as g}from"../core/canvas/render-source.js";const C=h({name:"dashboard",description:"render the canvas as a subscription tree",whenToUse:"you want the whole graph at a glance as a rendered tree \u2014 the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node's status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node's neighbors, and `canvas attention` to find which nodes are blocked on the user",help:{name:"canvas dashboard",summary:"render the canvas as an ASCII subscription tree \u2014 scoped to a root or the full forest",params:[{kind:"flag",name:"root",type:"string",required:!1,constraint:"Node id to use as the tree root. Omit for the full forest (all canvas roots)."}],output:[{name:"tree",type:"string",required:!0,constraint:"Multi-line ASCII tree."},{name:"nodes",type:"integer",required:!0,constraint:"Total node count in this view."},{name:"rows",type:"object[]",required:!0,constraint:"One per node: {node_id,name,status,kind,mode,ctx_tokens,asks}."}],outputKind:"object",effects:["Read-only: queries canvas.db and node telemetry files."]},run:u(async s=>{const e=s.root,t=w(),o=await t.listNodes();if(e!==void 0){if(!o.some(n=>n.node_id===e))throw new m({error:"not_found",message:`no node: ${e}`,next:"List nodes with `crtr node inspect list` to find a valid id."});let r={},d;try{r=await t.ticketCountsForView(e)}catch(n){d=n instanceof Error?n.message:String(n)}const c=await b(t,e,o,r);return{tree:await f(t,e,o,r,d),nodes:c.length,rows:c}}const i=await S(t,new Set,!1,o);let a={};try{a=await t.ticketCountsForNodes(o.map(r=>r.node_id))}catch{}return await g(t,i,a),{tree:await p(t,o,a),nodes:o.length,rows:i}},"run")});export{C as dashboardLeaf};

package/dist/commands/doc/delete.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const deleteLeaf: LeafDef;

package/dist/commands/doc/delete.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var r=(e,t)=>n(e,"name",{value:t,configurable:!0});import{defineLeaf as o}from"../../core/command.js";import{cliClient as i,rethrowAsCliError as d}from"../api-client.js";import{REF_CONSTRAINT as a}from"./shared.js";const u=o({name:"delete",description:"delete a document",whenToUse:"a document is wrong or obsolete",help:{name:"doc delete",summary:"delete a document",params:[{kind:"positional",name:"ref",required:!0,constraint:a}],output:[{name:"name",type:"string",required:!0,constraint:"The deleted document's full name."},{name:"id",type:"string",required:!0,constraint:"Object id."}],outputKind:"object",effects:["Deletes the document and pushes the deletion to its watchers; links to it resolve to deleted, showing its last preview."]},run:r(async e=>{try{return{...await i().docs.delete(e.ref)}}catch(t){d(t)}},"run"),render:r(e=>`<deleted name="${String(e.name)}" id="${String(e.id)}">`,"render")});export{u as deleteLeaf};

package/dist/commands/doc/edit.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const editLeaf: LeafDef;

package/dist/commands/doc/edit.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var s=(e,o)=>m(e,"name",{value:o,configurable:!0});import{defineLeaf as h}from"../../core/command.js";import{usage as d}from"../../core/errors.js";import{DOC_UNSET_FIELDS as u}from"../../api/dto/docs.js";import{cliClient as f}from"../api-client.js";import{parseReplaceBlocks as p}from"./replace-blocks.js";import{FIELD_FLAGS as t,REF_CONSTRAINT as y,fieldsFromInput as b,rethrowDocError as w,renderLinkReport as g,ruleParam as v}from"./shared.js";const q=h({name:"edit",description:"revise a document you have read",whenToUse:"a document you read needs a change to its body or fields",help:{name:"doc edit",summary:"revise a document you have read",guide:"The edit is made from the revision you last read (`crtr canvas read`); pass no revision. If someone edited it after your read, the edit is refused and nothing is overwritten. For a partial edit, pipe one or more literal blocks on stdin with --blocks: <<<<<<< SEARCH, old text, =======, new text, >>>>>>> REPLACE (markers on their own lines). Each SEARCH must match exactly once; empty REPLACE deletes text. Alternatively pipe a whole new body without --blocks, or use --replace JSON for scripts. Choose one mode. Pipe text straight in with a quoted heredoc (`<<'EOF'`); an unquoted one lets the shell expand `$` and backticks in the text, and the mangled text is what gets saved. A field flag replaces that field; omitted fields stay as they are.",params:[{kind:"positional",name:"ref",required:!0,constraint:y},{kind:"flag",name:"rationale",type:"string",required:!0,constraint:"Why this revision is made; recorded on the revision, never in the body."},{kind:"stdin",name:"body",required:!1,constraint:"Whole new body by default; with --blocks, exact SEARCH/REPLACE blocks."},{kind:"flag",name:"blocks",type:"bool",required:!1,constraint:"Interpret stdin as one or more whole-line <<<<<<< SEARCH / ======= / >>>>>>> REPLACE blocks; empty SEARCH is invalid, empty REPLACE deletes."},{kind:"flag",name:"replace",type:"string",required:!1,constraint:'JSON list `[{"old": "\u2026", "new": "\u2026"}]` of exact-text replacements; each `old` must match exactly once in the body you read.'},{kind:"flag",name:"verbatim",type:"bool",required:!1,constraint:"The body is the person's own text relayed unchanged; recorded on the revision."},t.preview("New one-line preview."),t.summary,t.privacy("Who beyond the owner may read it."),v("Replaces the whole rule list."),t.whyItExists,t.unlisted("Sets unlisted; remove it with `--unset unlisted`."),t.lintIgnore,t.extension,{kind:"flag",name:"unset",type:"enum",choices:[...u],required:!1,repeatable:!0,constraint:"Clear one optional field."}],output:[{name:"revision",type:"number",required:!0,constraint:"The new revision number."},{name:"unresolved_links",type:"string[]",required:!1,constraint:"`[[links]]` in the new body that name no document yet."},{name:"remote_links",type:"string[]",required:!1,constraint:"`[[links]]` whose first segment is no owner on this runtime: on another runtime, or misspelled."}],outputKind:"object",effects:["Commits a new revision based on your last read and pushes the edit to the document's watchers."]},run:s(async e=>{const o=e.ref;let n=typeof e.body=="string"&&e.body!==""?e.body:void 0,i;if(e.blocks===!0){if(e.replace!==void 0)throw d("choose --blocks or --replace, not both",{field:"blocks"});i=p(n??""),n=void 0}if(typeof e.replace=="string"){if(n!==void 0)throw d("give a stdin body or --replace, not both",{field:"replace",next:"Drop one of them and rerun."});try{const r=JSON.parse(e.replace);if(!Array.isArray(r)||r.length===0||r.some(a=>typeof a!="object"||a===null||typeof a.old!="string"||typeof a.new!="string"))throw new Error;i=r}catch{throw d('--replace must be a non-empty JSON list of {"old": string, "new": string}',{field:"replace",next:"Fix the JSON and rerun."})}}const l=e.unset===void 0?[]:[].concat(e.unset),c={rationale:e.rationale,...n!==void 0?{body:n}:{},...i!==void 0?{replace:i}:{},...e.verbatim===!0?{verbatim:!0}:{},...b(e),...l.length>0?{unset:l}:{}};try{return{...await f().docs.edit(o,c)}}catch(r){w(r,o)}},"run"),render:s(e=>`<edited name="${String(e.name)}" revision=${String(e.revision)}>${g(e)}`,"render")});export{q as editLeaf};

package/dist/commands/doc/history.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const historyLeaf: LeafDef;

package/dist/commands/doc/history.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var i=(t,e)=>s(t,"name",{value:e,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{cliClient as d,rethrowAsCliError as f}from"../api-client.js";import{REF_CONSTRAINT as m}from"./shared.js";const y=a({name:"history",description:"list the revisions of a document",whenToUse:"you need how or why a document reached its current state, or who wrote it first",help:{name:"doc history",summary:"list the revisions of a document",params:[{kind:"positional",name:"ref",required:!0,constraint:m},{kind:"flag",name:"diff",type:"int",required:!1,constraint:"A revision number; adds that revision's body diff against the revision it was made from."}],output:[{name:"revisions",type:"object[]",required:!0,constraint:"Each {number, rev_id, author_id, rationale, verbatim, created_at, parents}; oldest first. The first revision's author wrote the document."},{name:"diff",type:"string",required:!1,constraint:"Present with --diff."}],outputKind:"object",effects:["None."]},run:i(async t=>{try{return{...await d().docs.history(t.ref,typeof t.diff=="number"?{diff:t.diff}:void 0)}}catch(e){f(e)}},"run"),render:i(t=>{const e=t,n=e.revisions.map(r=>`<revision number=${r.number} rev="${r.rev_id}" author="${r.author_id??"unknown"}" at="${r.created_at}"${r.verbatim?" verbatim":""}${r.parents.length>1?` merges="${r.parents.join(",")}"`:""}>${r.rationale??""}</revision>`),o=[`<history name="${e.object.name}" id="${e.object.id}">`,...n,"</history>"];return e.diff!==void 0&&o.push("","```diff",e.diff,"```"),o.join(`
+`)},"render")});export{y as historyLeaf};

package/dist/commands/doc/lint.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const lintLeaf: LeafDef;

package/dist/commands/doc/lint.js

@@ -0,0 +1,2 @@
+var o=Object.defineProperty;var t=(n,e)=>o(n,"name",{value:e,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{cliClient as s,rethrowAsCliError as a}from"../api-client.js";import{ownerFromInput as c}from"./shared.js";const p=i({name:"lint",description:"check documents for authoring problems",whenToUse:"checking the documents you can change for bodies too long for their delivery, badly shaped previews, or links to nothing",help:{name:"doc lint",summary:"check documents for authoring problems",guide:'Checks the documents you can change: body length against how the document is delivered; the "When \u2026, read this because \u2026" preview shape where a rule delivers at preview; `[[links]]` that name no document; more than one workspace-open content document per repo your profile manages. A document skips a check named in its lint-ignore field.',params:[{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Check only this owner's documents: node | user | profile | profile:<name> | app | repo | repo:<handle>."}],output:[{name:"findings",type:"object[]",required:!0,constraint:"Each {name, severity, rule, message}; empty when clean."}],outputKind:"object",effects:["None."]},run:t(async n=>{try{return{...await s().docs.lint({...c(n),cwd:process.cwd()})}}catch(e){a(e)}},"run"),render:t(n=>{const{findings:e}=n;return e.length===0?"No findings.":e.map(r=>`<finding name="${r.name}" severity="${r.severity}" rule="${r.rule}">${r.message}</finding>`).join(`
+`)+"\nFix each with `crtr doc edit`, or add the rule to the document's lint-ignore field when it does not apply."},"render")});export{p as lintLeaf};

package/dist/commands/doc/list.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const listLeaf: LeafDef;

package/dist/commands/doc/list.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(e,n)=>o(e,"name",{value:n,configurable:!0});import{defineLeaf as r}from"../../core/command.js";import{CrtrError as s}from"../../core/errors.js";const m=r({name:"list",description:"documents are listed with crtr canvas list --type document",whenToUse:"never; this path exists only to name the canvas command",tier:"hidden",help:{name:"doc list",summary:"documents are listed with crtr canvas list --type document",params:[],output:[],outputKind:"object",effects:["None."]},run:t(async()=>{throw new s("wrong_command","crtr doc list does not exist; documents are listed with crtr canvas list --type document")},"run")});export{m as listLeaf};

package/dist/commands/doc/move.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const moveLeaf: LeafDef;

package/dist/commands/doc/move.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var r=(e,n)=>i(e,"name",{value:n,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{usage as m}from"../../core/errors.js";import{cliClient as d,rethrowAsCliError as s}from"../api-client.js";import{REF_CONSTRAINT as w,ownerFromInput as u,ownerParam as c}from"./shared.js";const v=a({name:"move",description:"rename a document or give it a new owner",whenToUse:"a document belongs under another name, or must outlive its node under another owner",help:{name:"doc move",summary:"rename a document or give it a new owner",params:[{kind:"positional",name:"ref",required:!0,constraint:w},{kind:"positional",name:"new-name",required:!1,constraint:"New name under its owner. Give it, --owner, or both."},c("New owner.")],output:[{name:"name",type:"string",required:!0,constraint:"The new full name."},{name:"id",type:"string",required:!0,constraint:"Object id, unchanged."}],outputKind:"object",effects:["Renames or re-owns the document; its id stays, links to it keep pointing at it, and no document body is rewritten."]},run:r(async e=>{const n=e.newName,o=u(e);if(n===void 0&&o.owner===void 0)throw m("give a new name, --owner, or both",{next:"Rerun with the new name after the document, or with --owner."});try{return{...await d().docs.move(e.ref,{...n!==void 0?{new_name:n}:{},...o,cwd:process.cwd()})}}catch(t){s(t)}},"run"),render:r(e=>`<moved name="${String(e.name)}" id="${String(e.id)}">`,"render")});export{v as moveLeaf};

package/dist/commands/doc/read.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const readLeaf: LeafDef;

package/dist/commands/doc/read.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var e=(r,a)=>t(r,"name",{value:a,configurable:!0});import{defineLeaf as n}from"../../core/command.js";import{CrtrError as o}from"../../core/errors.js";const i=n({name:"read",description:"documents are read with crtr canvas read",whenToUse:"never; this path exists only to name the canvas command",tier:"hidden",help:{name:"doc read",summary:"documents are read with crtr canvas read",params:[{kind:"positional",name:"ref",required:!1,constraint:"Ignored; read documents with crtr canvas read."}],output:[],outputKind:"object",effects:["None."]},run:e(async()=>{throw new o("wrong_command","crtr doc read does not exist; documents are read with crtr canvas read <name>")},"run")});export{i as readLeaf};

package/dist/commands/doc/replace-blocks.d.ts

@@ -0,0 +1,6 @@
+/** Parse line-delimited, literal SEARCH/REPLACE blocks. Delimiters are whole lines;
+ * the newline immediately before a delimiter belongs to syntax, not the text. */
+export declare function parseReplaceBlocks(source: string): Array<{
+    old: string;
+    new: string;
+}>;

package/dist/commands/doc/replace-blocks.js

@@ -0,0 +1,4 @@
+var h=Object.defineProperty;var o=(s,t)=>h(s,"name",{value:t,configurable:!0});import{usage as a}from"../../core/errors.js";function E(s){const t=s.split(`
+`),l=[];let e=0;const n=o(i=>{throw a(`block ${l.length+1}: ${i}`,{field:"blocks",next:"Use whole-line <<<<<<< SEARCH, =======, >>>>>>> REPLACE markers."})},"fail");for(;e<t.length&&!(t[e]===""&&e===t.length-1&&l.length>0);){t[e]!=="<<<<<<< SEARCH"&&n(`expected <<<<<<< SEARCH, got ${JSON.stringify(t[e])}`),e++;const i=[];for(;e<t.length&&t[e]!=="=======";)(t[e]===">>>>>>> REPLACE"||t[e]==="<<<<<<< SEARCH")&&n("missing ======= separator"),i.push(t[e++]);e===t.length&&n("missing ======= separator"),(i.length===0||i.length===1&&i[0]==="")&&n("empty SEARCH is not allowed"),e++;const r=[];for(;e<t.length&&t[e]!==">>>>>>> REPLACE";)(t[e]==="<<<<<<< SEARCH"||t[e]==="=======")&&n("missing >>>>>>> REPLACE terminator"),r.push(t[e++]);e===t.length&&n("missing >>>>>>> REPLACE terminator"),e++,l.push({old:i.join(`
+`),new:r.join(`
+`)})}return l.length===0&&n("expected at least one block"),l}o(E,"parseReplaceBlocks");export{E as parseReplaceBlocks};

package/dist/commands/doc/shared.d.ts

@@ -0,0 +1,25 @@
+import type { FlagParam } from '../../core/help.js';
+import type { DocOwnerFlag } from '../../api/dto/docs.js';
+export declare const REF_CONSTRAINT = "A document name (with or without [[ ]]) or a raw object id.";
+export declare const OWNER_VALUES = "node | user | profile | profile:<name> | app | repo | repo:<handle>";
+export declare function ownerParam(constraint: string): FlagParam;
+export declare function ruleParam(constraint: string): FlagParam;
+export declare const FIELD_FLAGS: {
+    preview: (constraint: string) => FlagParam;
+    kind: FlagParam;
+    summary: FlagParam;
+    privacy: (constraint: string) => FlagParam;
+    whyItExists: FlagParam;
+    unlisted: (constraint: string) => FlagParam;
+    lintIgnore: FlagParam;
+    extension: FlagParam;
+};
+/** Parse every field flag shared by write and edit; reports every bad value in one error. */
+export declare function fieldsFromInput(input: Record<string, unknown>): Record<string, unknown>;
+export declare function ownerFromInput(input: Record<string, unknown>): {
+    owner?: DocOwnerFlag;
+};
+/** Rethrow an API failure with the next step its code implies for `ref`. */
+export declare function rethrowDocError(err: unknown, ref: string): never;
+/** The link lines under a write or edit result. */
+export declare function renderLinkReport(r: Record<string, unknown>): string;

package/dist/commands/doc/shared.js

@@ -0,0 +1,2 @@
+var f=Object.defineProperty;var o=(e,t)=>f(e,"name",{value:t,configurable:!0});import{usage as m}from"../../core/errors.js";import{ApiError as w}from"../../api/errors.js";import{rethrowAsCliError as c}from"../api-client.js";import{RULE_ON as v,RULE_DELIVER as y,DOC_KINDS as g}from"../../api/dto/docs.js";import{PRIVACY_LEVELS_DTO as b}from"../../api/dto/objects.js";const O="A document name (with or without [[ ]]) or a raw object id.",p="node | user | profile | profile:<name> | app | repo | repo:<handle>";function j(e){return{kind:"flag",name:"owner",type:"string",required:!1,constraint:e,focusedHelp:{whenToUse:"Omit it for a document only this node and the nodes it points at need: the writing node owns it and it is deleted with the node, unless a kept document links to it. Give another owner when the document must outlive this node or reach other nodes by itself. A document worth another owner carries reusable current truth: a non-obvious procedure, a gotcha, a lasting preference, a convention across repos. Task notes, conversation summaries and facts the repo already records stay with the node or are not written. Before writing one, search for a document that already covers it (`crtr canvas search`) and revise that one with `crtr doc edit` instead of adding a near copy. When one document grows long, keep the most important content in it and move separate subjects into documents named under it (`topic/part`), each pointed at with a `[[link]]`. Choose the narrowest owner that still reaches the next agent who needs it.",value:`One of ${p}. \`node\` \u2014 the writing node; only this node loads it by rule, other nodes read it when pointed at it; deleted with the node. \`profile\` \u2014 the node's profile, or \`profile:<name>\`; loads for nodes running in that profile; stays on this runtime. \`app\` \u2014 the app that runs the node; kept until deleted; readable by that app's nodes. \`repo\` \u2014 the repo the node works in (from its working directory), or \`repo:<handle>\`; every clone and worktree of the repo shares it, and it syncs to collaborators over the repo's \`refs/crtr/docs\`. A repo owns only public documents: a private or friends document that should load in one repo is owned by \`user\` and carries a rule with \`if: {"repo": "<handle>"}\`. \`user\` \u2014 you, the person; loads for every node by its rules; readable by apps by privacy level. Default: the writing node; a person's own run (not a node) defaults to \`user\`. The owner becomes the start of the document's full name (\`<owner-handle>/<name>\`); \`crtr doc move --owner\` changes it later and keeps the id and every link.`,effects:["Decides who may read and change the document, where it syncs, and what deleting takes it with."]}}}o(j,"ownerParam");const k="`if` is a condition on the receiving node. Fields: `kind`, `mode`, `lifecycle`, `cwd`, `repo` (the handle of a repo the node works in), `profile`, `depth`. A field map is ANDed across fields; dotted fields resolve nested values. A scalar matches by equality (a list value matches when any element is equal); a list matcher matches by membership or overlap; an object matcher takes `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, `lte`. `all`, `any` and `not` combine conditions; field matchers beside them are ANDed in. An empty condition always matches; an unknown operator never matches. `match_frontmatter` uses the same language against the read file's YAML frontmatter.";function S(e){return{kind:"flag",name:"rule",type:"string",required:!1,repeatable:!0,constraint:e,focusedHelp:{whenToUse:"Omit it for most documents: a document with no rule is read when a node is pointed at it (`[[name]]`), finds it with `crtr canvas search`, or sees it in a listing. Add a rule only when the document must load on its own because of what a node is doing; every rule costs context in every node it fires on. Prefer the narrowest trigger: a `file-read` rule with a real glob over `boot` for knowledge about specific code; `boot` for knowledge about a person or process with no file boundary. When the whole document is one sentence, deliver `content` \u2014 a preview line would be longer than the document.",value:`One JSON object per occurrence: \`{"on": \u2026, "match"?: [globs], "match_frontmatter"?: {\u2026}, "if"?: {\u2026}, "deliver": \u2026}\`. \`on\` is the node's activity: ${v.join(" | ")}. \`boot\` \u2014 every session start of the node. \`workspace-open\` \u2014 the node's first message when it works in the document's repo. \`file-read\` \u2014 the node reads a file whose absolute path or basename matches a \`match\` glob, or whose frontmatter matches \`match_frontmatter\`. \`document-read\` \u2014 another document whose name matches is delivered at content, including an explicit read. \`command\` \u2014 a shell segment of a bash command matches (segments split on \`&&\`, \`||\`, \`;\`, \`|\` and newlines outside quotes, leading \`VAR=value\` dropped; \`*\` spans whole whitespace-separated tokens, \`?\` one character, quoted text is opaque). \`pre-command\` \u2014 as \`command\`, but runs before the command: when the node has not read the document, the command does not run and the document is returned instead; the node re-issues the command. \`slash-command\` \u2014 the document is a \`/<name>\` slash command whose body is the injected prompt. \`match\` is required on \`file-read\` (unless \`match_frontmatter\` is given), \`document-read\`, \`command\` and \`pre-command\`, and not allowed on \`boot\`, \`workspace-open\` and \`slash-command\`. `+k+` \`deliver\` is ${y.join(" | ")}: the bare name, the preview line, or the whole body. The flag set replaces the document's whole rule list; on \`crtr doc edit\`, \`--unset rules\` removes every rule.`,effects:["When several rules deliver one document to a node, the highest delivery wins: content over preview over name; content already in the node's context is not delivered again.","A document delivered at content is a read: it records the node as a watcher, so the node is pushed later edits.","The profile's delivery limit per owner caps what `boot` and `workspace-open` rules deliver for that owner.",'A rule that delivers at `preview` requires the preview in the shape "When <situation in the reader\'s work>, read this because <what the reader gains>"; `crtr doc lint` checks it. There the line alone decides whether a node that did not ask for the document opens it.']}}}o(S,"ruleParam");const N={preview:o(e=>({kind:"flag",name:"preview",type:"string",required:!1,constraint:e}),"preview"),kind:{kind:"flag",name:"kind",type:"enum",choices:[...g],required:!1,constraint:"knowledge is consulted for facts or procedures; preference directs behavior. Default knowledge."},summary:{kind:"flag",name:"summary",type:"string",required:!1,constraint:"A very short version of the content, shown in `crtr canvas list`."},privacy:o(e=>({kind:"flag",name:"privacy",type:"enum",choices:[...b],required:!1,constraint:e}),"privacy"),whyItExists:{kind:"flag",name:"why-it-exists",type:"string",required:!1,constraint:"The observed failure this document exists to prevent; shown only with `crtr canvas read --fields`."},unlisted:o(e=>({kind:"flag",name:"unlisted",type:"bool",required:!1,constraint:e}),"unlisted"),lintIgnore:{kind:"flag",name:"lint-ignore",type:"string",required:!1,repeatable:!0,constraint:"A `crtr doc lint` rule name to skip for this document."},extension:{kind:"flag",name:"extension",type:"string",required:!1,repeatable:!0,constraint:"One declared plugin field as `<plugin>.<field>=<json value>`."}};function h(e){return e===void 0?[]:Array.isArray(e)?e.map(String):[String(e)]}o(h,"list");function T(e){const t=[],n={};for(const[r,a]of[["preview","preview"],["kind","kind"],["summary","summary"],["privacy","privacy"],["why-it-exists","why_it_exists"]])typeof e[r]=="string"&&(n[a]=e[r]);typeof n.preview=="string"&&/[\r\n]/.test(n.preview)&&t.push("--preview must be one line"),e.unlisted===!0&&(n.unlisted=!0);const s=h(e["lint-ignore"]);s.length>0&&(n.lint_ignore=s);const i=h(e.rule);if(i.length>0){const r=[];i.forEach((a,u)=>{try{const d=JSON.parse(a);typeof d!="object"||d===null||Array.isArray(d)?t.push(`--rule #${u+1} must be a JSON object`):r.push(d)}catch{t.push(`--rule #${u+1} is not valid JSON: ${a}`)}}),n.rules=r}const l={};for(const r of h(e.extension)){const a=/^([^.=]+)\.([^=]+)=(.*)$/s.exec(r);if(!a){t.push(`--extension ${r} is not <plugin>.<field>=<json value>`);continue}try{(l[a[1]]??={})[a[2]]=JSON.parse(a[3])}catch{t.push(`--extension ${r}: the value after = is not valid JSON`)}}if(Object.keys(l).length>0&&(n.extensions=l),t.length>0)throw m(t.join("; "),{next:"Fix every value above and rerun; `--rule -h` gives the rule grammar."});return n}o(T,"fieldsFromInput");function D(e){const t=e.owner;if(t===void 0)return{};const n=String(t);if(!/^(node|user|profile|app|repo)$|^(profile|repo):.+$/.test(n))throw m(`invalid --owner ${n}`,{field:"owner",next:`Pass one of ${p}.`});return{owner:n}}o(D,"ownerFromInput");function R(e,t){e instanceof w&&(e.code==="read_first"&&c(e,`Read it first with \`crtr canvas read ${t}\`, then rerun the edit.`),e.code==="stale_revision"&&c(e,`Someone edited it after your read. Read it again with \`crtr canvas read ${t}\`, make your change on the current text, and rerun the edit.`)),c(e)}o(R,"rethrowDocError");function I(e){const t=[],n=e.unresolved_links,s=e.remote_links;return n?.length&&t.push(`Unresolved links (no document by these names yet): ${n.map(i=>`[[${i}]]`).join(", ")}`),s?.length&&t.push(`Not on this runtime: ${s.map(i=>`[[${i}]]`).join(", ")} \u2014 each may be on another runtime, or the name may be misspelled.`),t.map(i=>`
+${i}`).join("")}o(I,"renderLinkReport");export{N as FIELD_FLAGS,p as OWNER_VALUES,O as REF_CONSTRAINT,T as fieldsFromInput,D as ownerFromInput,j as ownerParam,I as renderLinkReport,R as rethrowDocError,S as ruleParam};

package/dist/commands/doc/write.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const writeLeaf: LeafDef;

package/dist/commands/doc/write.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var r=(e,n)=>o(e,"name",{value:n,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{cliClient as s,rethrowAsCliError as d}from"../api-client.js";import{FIELD_FLAGS as t,fieldsFromInput as l,ownerFromInput as m,ownerParam as u,renderLinkReport as c,ruleParam as h}from"./shared.js";const f=a({name:"write",description:"write a new document from a stdin body",whenToUse:"a spec, plan, map, finding, knowledge or preference should exist as a document other nodes can read; creation only \u2014 revise an existing one with `crtr doc edit`",help:{name:"doc write",summary:"write a new document from a stdin body",guide:"Most documents need only a name, a preview and a body: the writing node owns it, it has no delivery rules, and other nodes read it when pointed at it as `[[<name printed below>]]`, and each `[[link]]` in its body attaches that document's preview wherever this one is delivered in full. Give --owner or --rule only when the document must outlive this node or load on its own; each has focused help. Read, list and search documents with `crtr canvas read|list|search`.",params:[{kind:"positional",name:"name",required:!0,constraint:"Name under its owner: segments of letters, digits, `_` and `-`, joined by `/`. Must be free under that owner."},{kind:"stdin",name:"body",required:!0,constraint:"Document body (markdown), piped on stdin and saved byte for byte. Pipe it straight in with a quoted heredoc (`<<'EOF'`); an unquoted one lets the shell expand `$` and backticks in the text before it is saved."},{...t.preview("One line shown wherever the document is listed or delivered without its body, telling a reader whether to open it."),required:!0},t.kind,t.summary,t.privacy("Who beyond the owner may read it; default public. A repo-owned document must be public."),u("Whose document it is; default the writing node."),h("A delivery rule that loads the document into nodes by their activity."),t.whyItExists,t.unlisted("Keep it out of listings; reads, links and rules still work."),t.lintIgnore,t.extension],output:[{name:"name",type:"string",required:!0,constraint:"Full name, `<owner-handle>/<name>`; point at it as `[[name]]`."},{name:"id",type:"string",required:!0,constraint:"Object id."},{name:"unresolved_links",type:"string[]",required:!1,constraint:"`[[links]]` in the body that name no document yet; absent when every link resolves."},{name:"remote_links",type:"string[]",required:!1,constraint:"`[[links]]` whose first segment is no owner on this runtime: on another runtime, or misspelled."}],outputKind:"object",effects:["Creates the document at revision 1 and makes the writer a watcher, so it is pushed later edits."]},run:r(async e=>{const n={name:e.name,body:e.body,...l(e),...m(e),cwd:process.cwd()};try{return{...await s().docs.write(n)}}catch(i){d(i)}},"run"),render:r(e=>`<written name="${String(e.name)}" id="${String(e.id)}">${c(e)}`,"render")});export{f as writeLeaf};

package/dist/commands/doc.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerDoc(): BranchDef;

package/dist/commands/doc.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var e=(r,t)=>o(r,"name",{value:t,configurable:!0});import{defineBranch as n}from"../core/command.js";import{writeLeaf as a}from"./doc/write.js";import{editLeaf as i}from"./doc/edit.js";import{moveLeaf as m}from"./doc/move.js";import{historyLeaf as d}from"./doc/history.js";import{deleteLeaf as c}from"./doc/delete.js";import{lintLeaf as s}from"./doc/lint.js";import{readLeaf as f}from"./doc/read.js";import{listLeaf as p}from"./doc/list.js";function A(){return n({name:"doc",rootEntry:{concept:"a document \u2014 markdown written for readers: knowledge, preferences, specs, plans, maps",desc:"write, edit, move, delete and lint documents",useWhen:"writing or revising a document; read, list and search documents with `crtr canvas`"},help:{name:"doc",summary:"write, edit, move, delete and lint documents",model:"Reading, listing and searching documents are `crtr canvas read`, `crtr canvas list --type document` and `crtr canvas search`. A document is pointed at as `[[name]]`."},children:[a,i,m,d,c,s,f,p]})}e(A,"registerDoc");export{A as registerDoc};

package/dist/commands/human/components.d.ts

@@ -0,0 +1,4 @@
+import { type BranchDef } from '../../core/command.js';
+/** The product components the runtime registers, read through the daemon. */
+export declare function productComponents(): Promise<import("../../api/index.js").PageComponentDTO[]>;
+export declare const humanComponents: BranchDef;

package/dist/commands/human/components.js

@@ -0,0 +1,3 @@
+var s=Object.defineProperty;var e=(n,o)=>s(n,"name",{value:o,configurable:!0});import{defineBranch as c,defineLeaf as a}from"../../core/command.js";import{stateBlock as p}from"../../core/help.js";import{InputError as m}from"../../core/io.js";import{componentNames as i,renderComponentCatalog as d,renderComponentContract as u}from"../../core/human/component-docs.js";import{cliClient as h}from"../api-client.js";async function t(){return(await h().listPageComponents()).components}e(t,"productComponents");async function l(){const n=i(await t());return p("components",{count:n.length},n.join(", "))}e(l,"componentNameState");const g=a({name:"list",description:"list page components for selection",whenToUse:"choosing which components to put in an authored page module.",help:{name:"human components list",summary:"list page components for selection",inputNote:"No input parameters.",output:[{name:"catalog",type:"markdown",required:!0,constraint:"One concise selection entry per registry and product-registered component, grouped structural/response/display; no props or response schemas. A product component is written with the PascalCase tag derived from its registered kind."},{name:"follow_up",type:"string",required:!0,constraint:"Points to `crtr human components show <component>` for one selected component contract."}],outputKind:"object",effects:["None. Read-only."]},run:e(async()=>({catalog:d(await t()),follow_up:"Use `crtr human components show <component>` for one component contract."}),"run"),render:e(n=>`${String(n.catalog)}
+
+${String(n.follow_up)}`,"render")}),f=a({name:"show",description:"show one page component contract",whenToUse:"authoring one selected page component and needing its exact props, response contract, and shape in a page module.",help:{name:"human components show",summary:"show one page component contract",params:[{kind:"positional",name:"component",type:"string",required:!0,constraint:"Component name from the live <components> catalog below. Case-sensitive: registry components are PascalCase."}],output:[{name:"component",type:"string",required:!0,constraint:"The selected component name."},{name:"contract",type:"markdown",required:!0,constraint:"Hand-written props, response contract, and authoring example for that component. A shadcn family (Card, CardHeader, \u2026) shares one contract covering every member."}],outputKind:"object",effects:["None. Read-only."]},helpState:{leaf:l},run:e(async n=>{const o=n.component,r=u(o,await t());if(r===void 0)throw new m({error:"unknown_component",message:`unknown page component "${o}"`,field:"component",next:"Run `crtr human components show -h` and choose a component from its live catalog."});return{component:o,contract:r}},"run"),render:e(n=>String(n.contract),"render")}),N=c({name:"components",description:"discover page components and their contracts",whenToUse:"authoring a page module and choosing components, or needing one component\u2019s exact props and response contract.",help:{name:"human components",summary:"discover page components and their contracts",model:"These are the components already in scope in a page module \u2014 no import, ever. List is the selection catalog; show owns the full props, response contract, and authoring shape for one selected component."},children:[g,f]});export{N as humanComponents,t as productComponents};

package/dist/commands/human/feedback.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const humanFeedbackBranch: BranchDef;

package/dist/commands/human/feedback.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var a=(t,n)=>u(t,"name",{value:n,configurable:!0});import{envNodeId as h}from"../../shared/env.js";import{ApiError as p}from"../../api/index.js";import{defineBranch as k,defineLeaf as m}from"../../core/command.js";import{InputError as r}from"../../core/io.js";import{cliClient as s,rethrowAsCliError as d}from"../api-client.js";async function l(t){const n=t;try{const e=await s().getHumanRequest(n);if(e.kind!=="page")throw new r({error:"not_found",message:`no page ticket: ${n}`,field:"ticket_id",next:"Pass the ticket id from your bearings, or a page ticket_id from `crtr human list`."});return{requestId:n,inboxTicketId:e.inbox_ticket_id}}catch(e){if(e instanceof r)throw e;d(e,"Pass the ticket id from your bearings, or a page ticket_id from `crtr human list`.")}}a(l,"requirePageTicketId");const f=m({name:"list",description:"list a page ticket's feedback comments",whenToUse:"you are the feedback companion for a page ticket and need each comment's id and open/resolved status.",help:{name:"human feedback list",summary:"every feedback comment on one page ticket, with ids and open/resolved status",params:[{kind:"positional",name:"ticket_id",type:"string",required:!0,constraint:"The page ticket id from your bearings (also the page_id from human send)."}],output:[{name:"ticket_id",type:"string",required:!0,constraint:"The page ticket id."},{name:"open_count",type:"integer",required:!0,constraint:"How many comments remain open. Zero once feedback exists means all of it has been dealt with."},{name:"comments",type:"object[]",required:!0,constraint:"Each: {id, quote, context?, note, status, created_at, resolved_at?}; status is open or resolved. Oldest first."}],outputKind:"object",effects:["None. Read-only."]},run:a(async t=>{const n=await l(t.ticket_id);try{const e=await s().getHumanInboxPage(n.inboxTicketId);return{ticket_id:n.requestId,open_count:e.feedback.open_count,comments:e.feedback.comments}}catch(e){d(e)}},"run")}),b=m({name:"resolve",description:"mark one dealt-with feedback comment resolved",whenToUse:"you are the feedback companion and have dealt with an open comment \u2014 by revising the page or answering it in conversation.",help:{name:"human feedback resolve",summary:"mark one open feedback comment resolved \u2014 terminal, and only after the feedback has actually been dealt with",guide:"Resolution is your report that the work is done, not a triage state: revise the page or answer the comment in conversation first, then resolve. It appends no chat turn \u2014 briefly report the result in the conversation yourself. A resolved comment never reopens; a renewed concern arrives as a new comment.",params:[{kind:"positional",name:"comment_id",type:"string",required:!0,constraint:"A comment id from `crtr human feedback list`. The ticket is your own: it comes from the companion binding of the calling node."}],output:[{name:"resolved",type:"boolean",required:!0,constraint:"True when this call resolved the comment; false when it was already resolved."},{name:"ticket_id",type:"string",required:!0,constraint:"The page ticket id."},{name:"comment_id",type:"string",required:!0,constraint:"The comment id."},{name:"open_count",type:"integer",required:!1,constraint:"Comments still open after this resolution. Present when resolved is true."},{name:"reason",type:"string",required:!1,constraint:"comment_already_resolved when resolved is false."}],outputKind:"object",effects:["Marks the comment resolved in your own ticket's feedback record \u2014 the ticket comes from the calling companion's binding. Only the ticket's bound companion may resolve \u2014 any other node refuses with not_companion. A terminal ticket refuses with ticket_terminal \u2014 settlement already closed this collaboration."]},run:a(async t=>{const n=t.comment_id,e=h();if(e===void 0||e==="")throw new r({error:"no_node",message:"resolve runs inside the ticket\u2019s feedback companion (CRTR_NODE_ID unset)",next:"Run this from the companion conversation bound to the ticket."});const i=(await s().getNode(e)).review_binding;if(i==null||i.kind!=="page_feedback")throw new r({error:"not_companion",message:"this node is not a page-feedback companion \u2014 only the ticket\u2019s bound companion resolves its comments",next:"Resolve from the companion conversation bound to the ticket."});const c=await l(i.review_id);try{const o=await s().resolvePageFeedbackComment(c.inboxTicketId,n,e);return{resolved:!0,ticket_id:c.requestId,comment_id:n,open_count:o.feedback.open_count}}catch(o){if(o instanceof p&&o.status===409&&o.code==="comment_already_resolved")return{resolved:!1,ticket_id:c.requestId,comment_id:n,reason:"comment_already_resolved"};d(o)}},"run"),render:a(t=>t.resolved===!0?`Resolved feedback comment ${t.comment_id} \u2014 ${t.open_count} still open on ${t.ticket_id}.`:`Nothing to resolve for ${t.comment_id} \u2014 ${t.reason}.`,"render")}),I=k({name:"feedback",description:"operate on a page ticket's feedback comments",whenToUse:"you are a feedback companion working a page ticket's feedback comments.",help:{name:"human feedback",summary:"a page ticket's feedback comments \u2014 the person creates them on the page; the bound companion lists and resolves them",model:"Each comment is immutable once sent and open until resolved. resolve is terminal and companion-only, taken after the feedback has been dealt with by revising the page or answering in conversation."},children:[f,b]});export{I as humanFeedbackBranch};

package/dist/commands/human/prompts.d.ts

@@ -0,0 +1,21 @@
+import { type PageSource } from '../../core/human/page-schema.js';
+/** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
+ * directory, never ticket data; `nodeId` carries the originating node so a
+ * consumer can relate a ticket back to whatever that node belongs to, and
+ * `sessionName` is a presentation label only, while `profileName` lets product
+ * consumers resolve the applet or worker identity behind the ticket. Review
+ * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
+ * them. `nodeId` is stamped even when the daemon is unreachable — losing the
+ * labels is survivable, losing machine attribution is not.
+ *
+ * The same read answers who is sending: `lifecycle` decides whether the sender
+ * has a transcript a human is plausibly reading, which is what makes skipping
+ * the inbox safe. It is null for a bare shell (no node at all) and when the
+ * daemon cannot answer — neither is a terminal sender, so neither restricts
+ * delivery. */
+export declare function sender(): Promise<{
+    source: PageSource;
+    lifecycle: 'terminal' | 'resident' | null;
+}>;
+export declare function humanSend(pageSurface?: boolean): import("../../core/command.js").LeafDef;
+export declare const humanShow: import("../../core/command.js").LeafDef;

package/dist/commands/human/prompts.js

@@ -0,0 +1 @@
+var I=Object.defineProperty;var i=(n,e)=>I(n,"name",{value:e,configurable:!0});import{envNodeId as A}from"../../shared/env.js";import{defineLeaf as x}from"../../core/command.js";import{InputError as o}from"../../core/io.js";import{cliClient as l,rethrowAsCliError as S}from"../api-client.js";import{join as v}from"node:path";import{mkdtempSync as N,rmSync as j,writeFileSync as F}from"node:fs";import{tmpdir as W}from"node:os";import{productComponents as C}from"./components.js";import{preparePage as _}from"../../core/human/page-authoring.js";import{PageAuthoringError as E}from"../../core/human/page.js";import{isResponseBearingSlot as D,validateAuthoredPageManifest as U}from"../../core/human/page-schema.js";import{display as $}from"../../core/termrender/display.js";import{pageHelpText as q,resolveMaxPanes as M}from"./shared.js";const K=q().pageHint;function P(){return A()??null}i(P,"askingNode");async function Q(){const n=P();if(n===null||n==="")return{source:{},lifecycle:null};try{const e=l(),t=await e.getNode(n),a=t.name.trim(),r=t.profile_id===null?void 0:(await e.getProfile(t.profile_id)).name;return{source:{nodeId:n,...a===""?{}:{sessionName:a},...r===void 0?{}:{profileName:r}},lifecycle:t.lifecycle}}catch{return{source:{nodeId:n},lifecycle:null}}}i(Q,"sender");function B(n,e,t){const a=t==="terminal"||n.inbox===!0?!0:n.noInbox===!0?!1:e;return{placement:n.placement??"inline",inbox:a,reply:e}}i(B,"deliveryFrom");function g(n){try{return n()}catch(e){throw e instanceof E?new o({error:"invalid_page",message:e.message,field:"page",next:"Fix the authored page and submit again; the reported location is in the authored `.tsx` source."}):e}}i(g,"submitAuthoredPage");async function G(n){try{const e=await l().getHumanRequest(n);if(e.kind!=="page")throw new o({error:"unknown_page",message:`no page ${n} on this canvas`,field:"replace",next:"Pass the page_id a previous send returned, or omit --replace to raise a new page."});return(await l().getHumanInboxPage(e.inbox_ticket_id)).page}catch(e){if(e instanceof o)throw e;S(e,"Pass the page_id a previous send returned, or omit --replace to raise a new page.")}}i(G,"replacedPage");function L(n){const e=N(v(W(),"crtr-human-page-")),t=v(e,"page.tsx");return F(t,n,{encoding:"utf8",mode:384}),{dir:e,path:t}}i(L,"writePipedPage");function z(n){const e=n.page,t=n.document,a=typeof t=="string"&&t.trim()!==""?t:void 0;if(e!==void 0&&a!==void 0)throw new o({error:"bad_invocation",message:"received both --page and a piped page document",field:"page, document",next:"Pass exactly one page source: --page PATH or the document on stdin."});if(e===void 0&&a===void 0)throw new o({error:"missing_parameter",message:"a page source is required",field:"page, document",next:"Pass exactly one page source: --page PATH or the document on stdin."});if(e!==void 0){if(typeof e!="string")throw new o({error:"invalid_type",message:"--page must be a path",field:"page",next:"Retry with --page PATH."});return{sourceFile:e}}if(typeof a!="string")throw new o({error:"invalid_type",message:"stdin must contain a page document",field:"document",next:"Pipe the page document on stdin."});const r=L(a);return{sourceFile:r.path,tempDir:r.dir}}i(z,"pageInput");function J(){return"Queued for the user. Their answer is pushed to your inbox and wakes you when they respond \u2014 never poll, verify it opened, or block."}i(J,"queuedFollowUp");function ce(n=!1){const e=q(n);return x({name:"send",description:"send a durable page with explicit delivery",whenToUse:e.sendWhenToUse,help:{name:"human send",summary:e.sendSummary,guide:"Page authoring: `crtr human -h`.",params:[{kind:"stdin",name:"document",required:!1,allowPositional:!1,constraint:e.stdinConstraint},{kind:"flag",name:"page",type:"path",required:!1,constraint:`${K} ${e.pageFlagConstraint}`},{kind:"flag",name:"placement",type:"enum",choices:["inline","panel"],required:!1,default:"inline",constraint:"Where the page is delivered. inline renders in this conversation's transcript; panel opens from the inbox beside it."},{kind:"flag",name:"inbox",type:"bool",required:!1,constraint:"Project this page into the inbox. Mutually exclusive with --no-inbox."},{kind:"flag",name:"no-inbox",type:"bool",required:!1,constraint:"Do not project this page into the inbox, leaving this conversation's transcript as its only route to the user. Mutually exclusive with --inbox, and refused from a terminal node, whose transcript nobody reads once it finishes."},{kind:"flag",name:"replace",type:"string",required:!1,constraint:"Page id returned by an earlier send. Rewrites source in place while retaining its delivery and transcript anchor. Refused once the page is settled or canceled. Not combinable with delivery flags."}],output:[{name:"page_id",type:"string",required:!0,constraint:"Identifier for the page; pass it as --replace to revise source in place."},{name:"dir",type:"string",required:!0,constraint:e.dirConstraint},{name:"placement",type:"inline | panel",required:!0,constraint:"Resolved page placement."},{name:"inbox",type:"boolean",required:!0,constraint:"Whether the page is projected into the inbox."},{name:"reply",type:"boolean",required:!0,constraint:"Whether completion is delivered to the asking request identity. Not a flag: true exactly when the page has response-bearing components."},{name:"follow_up",type:"string",required:!0,constraint:"What happens next; never instructs the caller to poll."}],outputKind:"object",effects:["Writes one durable page request. Inbox projection follows the delivery flags, except from a terminal node, which always projects; completion delivery follows the page's own components.","A display-only page's inbox entry is a notice, not a task: it clears itself once the person has actually seen the page, wherever they see it.","A reply-bearing page records the asking node on the request and delivers completion directly to that node.","--replace rewrites source in place while retaining delivery and emitted time; open surfaces reload it without creating another page."]},run:i(async(t,a)=>{const{sourceFile:r,tempDir:f}=z(t),c=t.replace,k=["placement","inbox","noInbox"];if(t.inbox===!0&&t.noInbox===!0)throw new o({error:"bad_invocation",message:"received conflicting delivery flags",field:"inbox",next:"Pass at most one of --inbox and --no-inbox."});if(c!==void 0&&k.some(p=>a?.providedParams.has(p)===!0))throw new o({error:"bad_invocation",message:"--replace cannot change delivery",field:"replace",next:"Remove delivery flags: replacement retains the page placement, inbox, reply, and emitted time."});try{const p=await C();if(c!==void 0){const u=await G(c);if((await l().getHumanRequest(c)).state!=="pending")throw new o({error:"page_settled",message:`page ${c} already has a terminal outcome`,field:"replace",next:"The page was answered or canceled; nothing on it can change now. Raise a new page if more is needed."});const m=g(()=>_({sourceFile:r,source:u.source,productKinds:p,delivery:u.delivery})),H=await l().replaceHumanRequest(c,{page:{dialect:m.manifest.dialect,source:m.document}});return{page_id:c,dir:H.request_dir,...u.delivery,follow_up:"Replaced in place. Every open surface reloads it; delivery and emitted time are unchanged."}}const{source:T,lifecycle:w}=await Q();if(w==="terminal"&&t.noInbox===!0)throw new o({error:"invalid_page_delivery",message:"a terminal node cannot send a page --no-inbox",field:"inbox",next:"Drop --no-inbox. This node finishes, and nobody reads a finished node's transcript, so a page kept out of the inbox reaches no one."});const d=g(()=>_({sourceFile:r,source:T,productKinds:p})),R=d.manifest.slots.some(D),s=B(t,R,w);if(d.manifest=g(()=>U({...d.manifest,delivery:s},p)),!s.reply){const u=await l().createHumanRequest({page:{dialect:d.manifest.dialect,source:d.document},delivery:s,source:d.manifest.source,requester_node_id:null,creator_cwd:process.cwd()}),b=u.request_dir,m=s.placement==="inline"&&s.inbox?"Shown in this conversation and queued in the user's inbox.":s.placement==="inline"?"Shown in this conversation as passive page content with no inbox entry.":s.inbox?"Queued in the inbox; it opens in the panel and waits until dismissed.":"Published as passive page content with no inbox or response lifecycle.";return{page_id:u.request_id,dir:b,...s,follow_up:m}}const h=P();if(h===null||h==="")throw new o({error:"no_requester",message:"a response-bearing page must be sent from a crouter node",field:"page",next:"Run `crtr human send` from the node that should receive the answer."});const y=await l().createHumanRequest({page:{dialect:d.manifest.dialect,source:d.document},delivery:s,source:d.manifest.source,requester_node_id:h,creator_cwd:process.cwd()});return{page_id:y.request_id,dir:y.request_dir,...s,follow_up:J()}}finally{f!==void 0&&j(f,{recursive:!0,force:!0})}},"run")})}i(ce,"humanSend");const le=x({name:"show",description:"put a file live on the user's screen",whenToUse:"displaying a doc on screen while the user comments",help:{name:"human show",summary:"put a file live on screen in a tmux pane with crouter's renderer",guide:"The pane always watches the file and live-updates on every save \u2014 a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid). To put a rich document in front of the user as a durable inbox page, use `crtr human send --page PATH`; a page with no response-bearing components is a standalone announcement.",params:[{kind:"positional",name:"path",type:"path",required:!0,constraint:"Path to the file to render."},{kind:"flag",name:"window",type:"enum",choices:["auto","split","new"],required:!1,default:"auto",constraint:"Placement. Default auto."}],output:[{name:"pane_id",type:"string | null",required:!0,constraint:"Tmux pane id, or null when not displayed."},{name:"reason",type:"string | null",required:!0,constraint:"Why no pane was created, or null on success."}],outputKind:"object",effects:["Spawns a live-watch tmux pane when possible. No job. Always exits 0."]},run:i(async n=>{const e=n.path,t=n.window,a=t!==void 0?t:"auto";try{const r=$(e,{window:a,maxPanes:M()});return r.paneId!==void 0?{pane_id:r.paneId,reason:null}:{pane_id:null,reason:r.reason}}catch(r){return{pane_id:null,reason:`display failed: ${r instanceof Error?r.message:String(r)}`}}},"run")});export{ce as humanSend,le as humanShow,Q as sender};

package/dist/commands/human/queue.d.ts

@@ -0,0 +1,3 @@
+export declare const humanList: import("../../core/command.js").LeafDef;
+export declare const humanResolve: import("../../core/command.js").LeafDef;
+export declare const humanCancel: import("../../core/command.js").LeafDef;

package/dist/commands/human/queue.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var s=(e,t)=>w(e,"name",{value:t,configurable:!0});import{envNodeId as _}from"../../shared/env.js";import{ApiError as h}from"../../api/index.js";import{defineLeaf as u}from"../../core/command.js";import{InputError as c}from"../../core/io.js";import{paginate as y}from"../../core/pagination.js";import{cliClient as d,rethrowAsCliError as p}from"../api-client.js";async function b(){return(await d().listNodes()).map(e=>({node_id:e.node_id,name:e.name,cwd:e.cwd,parent:e.parent,status:e.status}))}s(b,"fetchNodeRefs");function q(e,t){if(e===void 0)return;const n=new Map(t.map(r=>[r.node_id,r]));let i=e;const o=new Set;for(;i.parent!==null&&!o.has(i.node_id);){o.add(i.node_id);const r=n.get(i.parent);if(r===void 0)break;i=r}return i}s(q,"resolveConversation");function v(e){const t=e?.sessionName?.trim();if(t!==void 0&&t!=="")return t;const n=e?.askedBy?.trim();return n===""?void 0:n}s(v,"readableSourceLabel");function x(e,t,n){const i=e.source.nodeId===void 0?void 0:n.get(e.source.nodeId),o=q(i,t),r=v(e.source);return{ticket_id:e.request_id,dir:e.request_dir,title:e.title,subtitle:e.subtitle??"",kind:e.kind,...e.kind==="page"?{emitted_at:e.emitted_at}:{blocked_since:e.blocked_since},...r===void 0?{}:{source_label:r},...i===void 0?{}:{asking_node_id:i.node_id,asking_node_name:i.name,cwd:i.cwd},...o===void 0?{}:{conversation_id:o.node_id,conversation_title:o.name}}}s(x,"summarizeTicket");async function k(e){try{const n=await d().getHumanRequest(e);return{request_id:n.request_id,kind:n.kind}}catch(n){(!(n instanceof h)||n.status!==404)&&p(n)}const t=(await d().listHumanInbox()).tickets.find(n=>n.request_id===e);if(t===void 0)throw new c({error:"not_found",message:`no interaction ticket: ${e}`,field:"ticket_id",next:"Pass a ticket_id from `crtr human list`."});return{request_id:t.request_id,kind:t.kind}}s(k,"requireInteraction");function g(e){return e instanceof h&&e.status===409&&(e.code==="already_settled"||e.code==="review_terminal_conflict")}s(g,"isAlreadySettled");const A=u({name:"list",description:"enumerate pending interactions",whenToUse:"discovering what is blocked on the user",help:{name:"human list",summary:"paginated list of pending interactions, oldest first",params:[{kind:"flag",name:"limit",type:"int",required:!1,default:20,constraint:"Default 20, max 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from a previous response's next_cursor. Omit on first call."}],output:[{name:"items",type:"object[]",required:!0,constraint:"Each: {ticket_id, dir, title, subtitle, kind, emitted_at? | blocked_since?}; pages use emitted_at, reviews use blocked_since. Enriched when derivable with claim_owner, source_label, asking_node_id/name, conversation_id/title. Oldest first."},{name:"next_cursor",type:"string | null",required:!0,constraint:"Pass on the next call to continue. null means no more items."},{name:"total",type:"integer | null",required:!0,constraint:"Total pending interactions."}],outputKind:"object",effects:["None. Read-only."]},run:s(async e=>{const t=Math.min(Math.max(1,e.limit),100),n=await b(),i=new Map(n.map(a=>[a.node_id,a])),o=(await d().listHumanInbox()).tickets.map(a=>x(a,n,i)).sort((a,l)=>{const m=`${a.emitted_at??a.blocked_since}|${a.ticket_id}`,f=`${l.emitted_at??l.blocked_since}|${l.ticket_id}`;return m<f?-1:m>f?1:0}),r=y(o,{limit:t,cursor:e.cursor},{defaultLimit:20,maxLimit:100,keyOf:s(a=>`${a.emitted_at??a.blocked_since}|${a.ticket_id}`,"keyOf"),total:"count"});return{items:r.items,next_cursor:r.next_cursor,total:r.total}},"run")});function $(e){let t;try{t=JSON.parse(e)}catch(n){throw new c({error:"invalid_json",message:`stdin is not valid JSON: ${String(n)}`,field:"stdin",next:'Pass {"responses":{"<component_id>":{...}}} on stdin.'})}if(typeof t.responses!="object"||t.responses===null||Array.isArray(t.responses))throw new c({error:"invalid_field",message:"responses must be an object keyed by the id of a response-bearing component",field:"responses",next:'Pass {"responses":{"<component_id>":{...}}}, or {"responses":{}} to acknowledge a page with no response-bearing components.'});return t.responses}s($,"parseResolveBody");const L=u({name:"resolve",description:"resolve one human page from stdin answers",whenToUse:"an API client or local tool is submitting answers for a pending human interaction.",tier:"hidden",help:{name:"human resolve",summary:"resolve a pending page with the given answers",params:[{kind:"positional",name:"ticket_id",type:"string",required:!0,constraint:"page_id from human send, or a page ticket_id from human list."},{kind:"stdin",name:"body",required:!0,constraint:"JSON {responses:{<component_id>:{...}}} \u2014 one typed response object per response-bearing component of the page."}],output:[{name:"resolved",type:"boolean",required:!0,constraint:"True when this call completed the page."},{name:"ticket_id",type:"string",required:!0,constraint:"Interaction request id."},{name:"reason",type:"string",required:!1,constraint:"already_settled when resolved is false."}],outputKind:"object",effects:["The daemon settles the request and directly delivers a reply-bearing completion to its asking node."]},run:s(async e=>{const t=e.ticket_id,n=await k(t);if(n.kind!=="page")throw new c({error:"not_found",message:`no page for interaction: ${t}`,field:"ticket_id",next:"Pass a pending page ticket_id from `crtr human list`."});try{await d().respondHumanRequest(n.request_id,{responses:$(e.body),actor:_()??"human"})}catch(i){if(g(i))return{resolved:!1,ticket_id:t,reason:"already_settled"};p(i)}return{resolved:!0,ticket_id:t}},"run")}),P=u({name:"cancel",description:"retract a pending page/review",whenToUse:"a page or review went stale before the user completed it",help:{name:"human cancel",summary:"retract a pending page or review",params:[{kind:"positional",name:"ticket_id",type:"string",required:!0,constraint:"page_id returned by human send, or ticket_id returned by human list."},{kind:"flag",name:"reason",type:"string",required:!1,constraint:"Optional short note delivered to the asking node explaining why it was retracted."}],output:[{name:"canceled",type:"boolean",required:!0,constraint:"True when the interaction was retracted; false when it was already terminal."},{name:"ticket_id",type:"string",required:!0,constraint:"The interaction request id."},{name:"reason",type:"string",required:!1,constraint:"already_settled when canceled is false."}],outputKind:"object",effects:["The daemon removes the request from the human inbox and directly notifies its asking node when it has one."]},run:s(async e=>{const t=e.ticket_id,n=await k(t),i=e.reason,o={...i===void 0||i===""?{}:{reason:i},actor:_()??"human"};try{n.kind==="review"?await d().cancelReview(n.request_id,o):await d().cancelHumanRequest(n.request_id,o)}catch(r){if(g(r))return{canceled:!1,ticket_id:t,reason:"already_settled"};p(r)}return{canceled:!0,ticket_id:t}},"run"),render:s(e=>e.canceled===!0?`Canceled human interaction ${e.ticket_id} \u2014 it left the human inbox.`:`Nothing to cancel for ${e.ticket_id} \u2014 ${e.reason??"nothing to cancel"}.`,"render")});export{P as humanCancel,A as humanList,L as humanResolve};

package/dist/commands/human/request.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const humanRequestBranch: BranchDef;

package/dist/commands/human/request.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var a=(e,t)=>y(e,"name",{value:t,configurable:!0});import{existsSync as p,readFileSync as f}from"node:fs";import{defineBranch as w,defineLeaf as o}from"../../core/command.js";import{InputError as s}from"../../core/io.js";import{cliClient as d,rethrowAsCliError as c}from"../api-client.js";function g(e,t,n){if(!p(e))throw new s({error:"not_found",message:`no such file: ${e}`,field:t,next:`Pass --${t} PATH pointing at a JSON file holding ${n}.`});let r;try{r=f(e,"utf8")}catch(m){throw new s({error:"unreadable_file",message:`could not read ${e}: ${String(m)}`,field:t,next:"Pass a readable JSON file."})}let i;try{i=JSON.parse(r)}catch(m){throw new s({error:"invalid_json",message:`${e} is not valid JSON: ${String(m)}`,field:t,next:`Write ${n} into the file as JSON.`})}if(typeof i!="object"||i===null||Array.isArray(i))throw new s({error:"invalid_field",message:`${e} must hold a JSON object`,field:t,next:`Write ${n} into the file as a JSON object.`});return i}a(g,"readJsonFile");function q(e){const t=/\.html?$/i.test(e);if(!t&&!e.endsWith(".tsx"))throw new s({error:"invalid_field",message:`page source file must be .tsx, .html, or .htm: ${e}`,field:"page",next:"Author the page as a .tsx module or a complete .html document."});if(!p(e))throw new s({error:"not_found",message:`page source file does not exist: ${e}`,field:"page",next:"Pass --page PATH pointing at the authored page."});return{dialect:t?"html":"jsx",source:f(e,"utf8")}}a(q,"readPageFile");function u(e){const t=typeof e.request_id=="string"?e.request_id.trim():"";if(t==="")throw new s({error:"missing_request_id",message:"a request id is required",field:"request_id",next:"Pass the request_id returned by `crtr human request create`."});return t}a(u,"requestId");function l(e,t=!0){return{...t?{request_id:e.request_id}:{},state:e.state,title:e.title,...e.subtitle===void 0?{}:{subtitle:e.subtitle},source:e.source,emitted_at:e.emitted_at,...e.settled_at===void 0?{}:{settled_at:e.settled_at},...e.responses===void 0?{}:{responses:e.responses},...e.reason===void 0?{}:{reason:e.reason},...e.actor===void 0?{}:{actor:e.actor},...e.action===void 0?{}:{action:e.action},...e.delivery===void 0?{}:{delivery:e.delivery}}}a(l,"requestResult");const h=[{name:"state",type:"pending | answered | dismissed | canceled",required:!0,constraint:"answered: the person (or an authorized responder) submitted the typed responses. dismissed: the recipient surface closed it unanswered. canceled: the requester withdrew it."},{name:"title",type:"string",required:!0,constraint:"Page title as currently published."},{name:"subtitle",type:"string",required:!1,constraint:"Page subtitle when the page carries one."},{name:"source",type:"object",required:!0,constraint:"Stored provenance from the request creator: sessionName?, askedBy?, emittedAt?, profileName?, nodeId?."},{name:"emitted_at",type:"string",required:!0,constraint:"UTC ISO instant of creation; a replace never changes it."},{name:"settled_at",type:"string",required:!1,constraint:"UTC ISO instant of the terminal result. Absent while pending."},{name:"responses",type:"object",required:!1,constraint:"The typed slot map, keyed by response-bearing component id. Present only when state is answered."},{name:"reason",type:"string",required:!1,constraint:"Note recorded by the dismissal or the withdrawal."},{name:"actor",type:"string",required:!1,constraint:"Who settled it, when the settling surface named itself."},{name:"action",type:"object",required:!1,constraint:"{name, payload} frozen at creation; an omitted payload is frozen as null. Absent when no action is bound."},{name:"delivery",type:"object",required:!1,constraint:"Completion-delivery state for the bound action: {state: none | pending | running | accepted | permanent_failed, attempt, next_attempt_at?, accepted_at?, permanent_failed_at?, last_failure?}. Absent when no action is bound."}],b=[{name:"request_id",type:"string",required:!0,constraint:"The request \u2014 the same 64-hex id the human inbox lists it under."},...h],v=o({name:"create",description:"create a durable request from a JSON request file",whenToUse:"a script or backend needs a human decision that must survive its own exit, rather than an answer routed back to a live node.",help:{name:"human request create",summary:"create one durable human request from the typed create object",params:[{kind:"flag",name:"request-file",type:"path",required:!0,constraint:'JSON file holding the create object: {"page":{"dialect":"jsx"|"html","source":"<the authored page text, inline>"}, "delivery"?:{"placement":"inline"|"panel"}, "source"?:{"sessionName"?,"askedBy"?,"emittedAt"?,"profileName"?,"nodeId"?}, "creator_cwd"?:"<absolute dir>", "action"?:{"name":"<declared action>","payload":<any JSON, null when omitted>}}. The page text is inline, never a path \u2014 the request must stay readable after the creating process is gone. creator_cwd defaults to this directory and is the scope the action name resolves from. delivery.inbox and delivery.reply are pinned: a programmatic request is always answerable from the inbox and never routes to an agent bridge. Unknown fields are rejected.'}],output:[{name:"request_id",type:"string",required:!0,constraint:"The created request \u2014 pass it to get/replace/respond/cancel. Stable, and the deduplication key every completion destination keys on."},{name:"action",type:"object",required:!1,constraint:"{name} of the frozen action binding. Absent when the request carries no action."}],outputKind:"object",effects:["Publishes one durable page ticket into the human inbox. It has no reply bridge and outlives this process.","An action name is resolved from the humanActions map in scope config (project ancestors, then user) BEFORE anything is written \u2014 an unknown or unusable name is rejected and leaves no inbox row for a person to answer.","A resolved action is frozen onto the ticket: name, payload, resolved argv, and cwd. replace can never change it; a different effect needs a cancel and a new request."]},run:a(async e=>{const t=e.requestFile,n=g(t,"request-file","the create object");n.creator_cwd===void 0&&(n.creator_cwd=process.cwd());try{const r=await d().createHumanRequest(n);return{request_id:r.request_id,...r.action===void 0?{}:{action:r.action}}}catch(r){c(r)}},"run")}),_=o({name:"get",description:"read one request, its terminal result, and its delivery state",whenToUse:"you need the current state of a request you created \u2014 including the answers, once someone has settled it.",help:{name:"human request get",summary:"read one durable request",params:[{kind:"positional",name:"request_id",type:"string",required:!0,constraint:"request_id returned by `human request create`."}],output:[...b],outputKind:"object",effects:["None. Read-only."]},run:a(async e=>{try{return l(await d().getHumanRequest(u(e)))}catch(t){c(t)}},"run")}),x=o({name:"replace",description:"revise a pending request's page in place",whenToUse:"what you are asking changed while the request is still pending, and the same request should keep its identity and its frozen action.",help:{name:"human request replace",summary:"republish a pending request's page",params:[{kind:"positional",name:"request_id",type:"string",required:!0,constraint:"request_id returned by `human request create`."},{kind:"flag",name:"page",type:"path",required:!0,constraint:"The revised page: a .tsx module or a complete .html/.htm document. Read here and sent inline."}],output:[...h],outputKind:"object",effects:["Rewrites the page and its typed response contract in place; open surfaces reload it without a second request.","Identity is untouched: request id, provenance, emitted time, delivery, and the frozen action binding all survive verbatim.","Refused with already_settled once the request has a terminal result \u2014 a settled request is revised by cancelling and creating a new one."]},run:a(async e=>{const t=u(e),n={page:q(e.page)};try{return l(await d().replaceHumanRequest(t,n),!1)}catch(r){c(r)}},"run")}),k=o({name:"respond",description:"settle a pending request with typed answers",whenToUse:"an authorized host is submitting the answers on the person's behalf, rather than the person answering in their inbox.",help:{name:"human request respond",summary:"answer a pending request",params:[{kind:"positional",name:"request_id",type:"string",required:!0,constraint:"request_id returned by `human request create`."},{kind:"flag",name:"response-file",type:"path",required:!0,constraint:'JSON file holding the respond object: {"responses":{"<component_id>":{...}}, "actor"?:"<who answered>"}. One typed response per response-bearing component; the daemon validates the complete map against the currently published page.'}],output:[...h],outputKind:"object",effects:["Settles the request as answered and drops it from the human inbox.","Competes with the person's own answer, a recipient dismissal, and a requester cancel through one first-writer-wins store: a losing attempt returns already_settled and changes nothing.","When an action is bound, the winning settlement enqueues one at-least-once completion delivery keyed on the request id."]},run:a(async e=>{const t=u(e),n=g(e.responseFile,"response-file","the respond object");try{return l(await d().respondHumanRequest(t,n),!1)}catch(r){c(r)}},"run")}),j=o({name:"cancel",description:"withdraw a pending request",whenToUse:"the decision you asked for stopped mattering, or the effect must change \u2014 the action binding is immutable, so a new effect needs a new request.",help:{name:"human request cancel",summary:"withdraw a pending request",params:[{kind:"positional",name:"request_id",type:"string",required:!0,constraint:"request_id returned by `human request create`."},{kind:"flag",name:"reason",type:"string",required:!1,constraint:"Short note recorded on the terminal result and carried in the completion document."}],output:[...h],outputKind:"object",effects:["Settles the request as canceled and drops it from the human inbox \u2014 the person is no longer asked.","Races the person's answer through the same first-writer-wins store; whoever lands first is authoritative and the loser returns already_settled.","When an action is bound, the winning settlement enqueues one completion delivery carrying the canceled event."]},run:a(async e=>{const t=u(e),n=typeof e.reason=="string"&&e.reason!==""?e.reason:void 0;try{return l(await d().cancelHumanRequest(t,n===void 0?{}:{reason:n}),!1)}catch(r){c(r)}},"run")}),N=w({name:"request",description:"durable requests that outlive the process that made them",whenToUse:"a script or backend needs a human decision whose outcome must survive its own exit, instead of an answer pushed back to a live node.",help:{name:"human request",summary:"durable programmatic human requests \u2014 create, read, revise, and settle",model:"A request is the same page ticket `human send` publishes, minus the agent bridge: nothing waits on it, and the outcome is read with `get` or carried to a local command by a named action. Reach for it when the caller will be gone before the person answers; when a live node should receive the answer, use `crtr human send` instead.\n\nThe page and its typed response contract stay revisable with `replace` while pending. The action binding does not: name, payload, resolved argv, and cwd are frozen at creation, so a different effect means `cancel` plus a new request. An action is a name declared in the humanActions map of scope config \u2014 there is no command, shell string, or callback URL anywhere in this surface.\n\nA request ends exactly once. `respond` (an authorized host answering), the person answering in their own inbox, a recipient dismissal, and `cancel` all compete through one first-writer-wins settlement; the loser gets already_settled and no second delivery. Only the winner enqueues the completion document, delivered at least once \u2014 the receiving command must deduplicate on the request id."},children:[v,_,x,k,j]});export{N as humanRequestBranch};

package/dist/commands/human/review.d.ts

@@ -0,0 +1,2 @@
+import { type BranchDef } from '../../core/command.js';
+export declare const humanReviewBranch: BranchDef;

package/dist/commands/human/review.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var o=(e,t)=>y(e,"name",{value:t,configurable:!0});import{envNodeId as _}from"../../shared/env.js";import{randomUUID as q}from"node:crypto";import{defineBranch as w,defineLeaf as s}from"../../core/command.js";import{InputError as l}from"../../core/io.js";import{cliClient as r}from"../api-client.js";function d(){const e=_();return e===void 0||e===""?null:e}o(d,"nodeActor");function x(){const e=d();if(e!==null)return e;throw new l({error:"review_origin_unavailable",message:"a review must be filed from a node with a live or resumable session",field:"CRTR_NODE_ID",next:"Run this from the node whose document context should be forked for the review."})}o(x,"requireOriginNode");function b(e){if(typeof e=="string"&&e.trim()!=="")return e.trim();throw new l({error:"missing_parameter",message:"a non-empty subtitle is required",field:"subtitle",next:"Run `crtr human review new -h` and provide one plain-English sentence explaining the review needed and why it matters."})}o(b,"requireSubtitle");function v(e,t){if(typeof e=="string"&&e.trim()!=="")return e;throw new l({error:"missing_parameter",message:"non-empty comment text is required on stdin",field:"text",next:`Run \`crtr human review comment ${t} -h\` and pipe the comment text on stdin.`})}o(v,"requireCommentText");function h(e,t){if(!(t?.providedParams.has("deliver")??e.deliver!==void 0))return;const i=e.deliver;return i==="wake"||i==="quiet"?i:void 0}o(h,"explicitDeliver");function f(e,t=!0){const{comment:n}=e;return{comment_id:n.comment_id,status:n.status,revision:n.revision,...t?{anchor:n.anchor}:{},author:n.author,text:n.text,changed:e.changed,delivery:e.delivery??null}}o(f,"mutationOutput");function k(e){return{comment_id:e.comment_id,status:e.status,revision:e.revision,anchor:{line:e.anchor.line,end_line:e.anchor.end_line},anchor_state:e.anchor_state,author:e.author,updated_by:e.updated_by,created_at:e.created_at,updated_at:e.updated_at,text_preview:e.text.slice(0,200)}}o(k,"commentPreview");const C=s({name:"new",description:"queue a document review with a collaborating companion agent",whenToUse:"filing a live document for a person to review alongside a companion agent.",help:{name:"human review new",summary:"queue a live document review and return its ticket handle immediately",guide:"The person reviews the document in the attach viewer alongside a collaborating companion agent. The daemon reads the document as you and snapshots its current revision into the review. When the person submits, their edits are saved as a new revision of the document and the approval is pushed to your inbox. If the document gets a new revision while the review is open, the save is refused as `stale_revision` and the review stays open; do not edit a document while it is under review.",params:[{kind:"positional",name:"document",type:"string",required:!0,constraint:"The document to review: a name, `<owner>/<name>` or id, `[[ ]]` optional. It must have one head; merge several heads first."},{kind:"flag",name:"subtitle",type:"string",required:!0,constraint:"One plain-English sentence stating the review needed and why it matters."}],output:[{name:"review_id",type:"string",required:!0,constraint:"Daemon-owned review id for the document, comments, and companion."},{name:"document",type:"string",required:!0,constraint:"The reviewed document's `<owner>/<name>`."},{name:"review_dir",type:"string",required:!0,constraint:"Directory containing the review's document.md snapshot and immutable result.json."},{name:"result_path",type:"string",required:!0,constraint:"The immutable terminal result path: <review_dir>/result.json."},{name:"follow_up",type:"string",required:!0,constraint:"The review remains live for the person and companion; approval is delivered to the origin inbox."}],outputKind:"object",effects:["Records your read of the document and creates the durable review, its `document.md` snapshot, and the companion session fork.","On submit, a changed snapshot becomes a new revision authored by the person; this command does not submit an approval."]},run:o(async e=>{const t=b(e.subtitle),n=await r().createReview({origin_kind:"ticket",origin_node_id:x(),document:e.document,idempotency_key:q(),subtitle:t});return{review_id:n.review_id,document:n.document??null,review_dir:n.review_dir,result_path:`${n.review_dir}/result.json`,follow_up:"The review is live for the person in the attach viewer with its companion agent. Approval is pushed to the origin inbox when submitted."}},"run")}),R=s({name:"create",description:"add an anchored review comment",whenToUse:"recording a new finding or instruction against one or more document lines.",help:{name:"human review comment create",summary:"add a daemon-owned comment anchored to document lines",guide:"Without --review, the daemon targets the calling companion node's open review. Comment text is supplied on stdin; agent comments use whole-line anchors.",params:[{kind:"flag",name:"review",type:"string",required:!1,constraint:"Review id. Omit only to target the calling companion node's open review."},{kind:"flag",name:"line",type:"int",required:!0,constraint:"First 1-based document line in the anchor."},{kind:"flag",name:"end-line",type:"int",required:!1,constraint:"Last 1-based document line in the anchor. Default: --line."},{kind:"flag",name:"deliver",type:"enum",choices:["wake","quiet"],required:!1,constraint:"wake interrupts the companion now; quiet leaves a durable message for its next turn. Default: wake unless the caller is the companion."},{kind:"stdin",name:"text",required:!0,constraint:"Non-empty comment text."}],output:[{name:"comment_id",type:"string",required:!0,constraint:"Daemon-owned comment id."},{name:"status",type:"string",required:!0,constraint:"Current comment status: open, resolved, or deleted."},{name:"revision",type:"integer",required:!0,constraint:"Current per-comment revision."},{name:"author",type:"object",required:!0,constraint:"Daemon-derived human or node attribution."},{name:"text",type:"string",required:!0,constraint:"Stored full comment text."},{name:"changed",type:"boolean",required:!0,constraint:"Whether this invocation changed the comment."},{name:"delivery",type:"object | null",required:!0,constraint:"Best-effort companion notification outcome, or null when no notification was needed."}],outputKind:"object",effects:["Creates a daemon-owned comment and audit event, then best-effort notifies the companion."]},run:o(async(e,t)=>{const n=e.review,i=e.line,a=e.endLine,u=await r().createReviewComment(n,{text:v(e.text,"create"),anchor:{line:i,end_line:a??i},actor_node_id:d(),...h(e,t)===void 0?{}:{deliver:h(e,t)}});return f(u,!1)},"run")}),j=s({name:"list",description:"list review comments in render order",whenToUse:"choosing a comment to inspect or checking the current anchored comment set.",help:{name:"human review comment list",summary:"list render-ordered review comments with short text previews",guide:"Without --review, the daemon targets the calling companion node's open review. Use show for full comment text and audit history.",params:[{kind:"flag",name:"review",type:"string",required:!1,constraint:"Review id. Omit only to target the calling companion node's open review."},{kind:"flag",name:"status",type:"enum",choices:["open","resolved","deleted","all"],required:!1,default:"open",constraint:"Comment statuses to include. Default: open."}],output:[{name:"review_id",type:"string",required:!0,constraint:"Resolved daemon-owned review id."},{name:"comments",type:"object[]",required:!0,constraint:"Comments in render order with status, anchor, attribution, and a 200-character text_preview."},{name:"follow_up",type:"string",required:!0,constraint:"Points to show for full text and per-comment history."}],outputKind:"object",effects:["None. Read-only."]},run:o(async e=>{const t=e.review,n=e.status,i=await r().listReviewComments(t,t===void 0?{status:n,actor_node_id:d()}:{status:n});return{review_id:i.review_id,comments:i.comments.map(k),follow_up:"Use `crtr human review comment show <comment_id>` for full comment text and event history."}},"run")}),T=s({name:"show",description:"read one comment and its event history",whenToUse:"you need a comment's full text or complete per-comment audit history.",help:{name:"human review comment show",summary:"read one full review comment and its event history",params:[{kind:"positional",name:"comment_id",type:"string",required:!0,constraint:"Daemon-owned comment id from comment list."}],output:[{name:"comment",type:"object",required:!0,constraint:"Full daemon-owned comment projection, including text and attribution."},{name:"events",type:"object[]",required:!0,constraint:"Complete append-only event history for this comment, in event sequence order."}],outputKind:"object",effects:["None. Read-only."]},run:o(async e=>{const t=await r().getReviewComment(e.comment_id);return{comment:t.comment,events:t.events}},"run")});function c(e){const t=e==="edit";return s({name:e,description:e==="edit"?"replace a comment's text":`${e} one review comment`,whenToUse:e==="edit"?"changing the stored text of an existing open or resolved comment.":`${e==="resolve"?"marking a comment addressed":e==="reopen"?"returning a resolved comment to open":"retaining a terminal comment tombstone while removing it from active work"}.`,help:{name:`human review comment ${e}`,summary:e==="edit"?"replace a review comment's full text":`${e} a review comment`,guide:t?"Replacement comment text is supplied on stdin.":void 0,params:[{kind:"positional",name:"comment_id",type:"string",required:!0,constraint:"Daemon-owned comment id from comment list."},{kind:"flag",name:"deliver",type:"enum",choices:["wake","quiet"],required:!1,constraint:`wake interrupts the companion now; quiet leaves a durable message for its next turn. Default: ${e==="resolve"||e==="delete"?"quiet":"wake"} unless the caller is the companion.`},...t?[{kind:"stdin",name:"text",required:!0,constraint:"Non-empty replacement comment text."}]:[]],output:[{name:"comment_id",type:"string",required:!0,constraint:"Daemon-owned comment id."},{name:"status",type:"string",required:!0,constraint:"Current comment status: open, resolved, or deleted."},{name:"revision",type:"integer",required:!0,constraint:"Current per-comment revision."},{name:"anchor",type:"object",required:!0,constraint:"Current whole-line anchor."},{name:"author",type:"object",required:!0,constraint:"Daemon-derived human or node attribution."},{name:"text",type:"string",required:!0,constraint:"Stored full comment text."},{name:"changed",type:"boolean",required:!0,constraint:"Whether this invocation changed the comment."},{name:"delivery",type:"object | null",required:!0,constraint:"Best-effort companion notification outcome, or null when no notification was needed."}],outputKind:"object",effects:["Mutates the daemon-owned comment and appends an audit event when its state changes; notification is best-effort."]},run:o(async(n,i)=>{const a=n.comment_id,u=d(),p=h(n,i),m={actor_node_id:u,...p===void 0?{}:{deliver:p}},g=e==="edit"?await r().editReviewComment(a,{...m,text:v(n.text,"edit")}):e==="resolve"?await r().resolveReviewComment(a,m):e==="reopen"?await r().reopenReviewComment(a,m):await r().deleteReviewComment(a,m);return f(g)},"run")})}o(c,"commentMutationLeaf");const D=w({name:"comment",description:"create, inspect, and update daemon-owned review comments",whenToUse:"working with the anchored comments on a document review.",help:{name:"human review comment",summary:"operate on daemon-owned anchored review comments",model:"create and list address a review; all other verbs address one comment id. Create, edit, and reopen default to wake, while resolve and delete default to quiet."},children:[R,j,T,c("edit"),c("resolve"),c("reopen"),c("delete")]}),K=w({name:"review",description:"queue a document review or operate on its anchored comments",whenToUse:"a person and companion agent should collaborate on a live document review, or you need to work with that review's anchored comments.",help:{name:"human review",summary:"queue live document reviews and manage their daemon-owned comments",model:"new creates the durable review, ticket, and companion. comment contains the operations on the review's shared anchored comments."},children:[C,D]});export{K as humanReviewBranch};