@ctrl-spc/cs 0.7.3 → 0.7.4

package/dist/workflows.js

@@ -1,3 +1,4 @@
+import { absolutePathToken } from './local-paths.js';
 async function read(query, subject) {
     const { data, error } = await query;
     if (error)
@@ -5,29 +6,31 @@ async function read(query, subject) {
     return data ?? [];
 }
 /**
- * A workflow, its stages in order, and the exits off them.
+ * A workflow, its stages in order, the exits off them and its branches.
  *
  * SORTED HERE RATHER THAN TRUSTED, which is the web reader's own rule: order is
  * the whole point of a workflow, positions are deliberately not unique (a
  * reorder rewrites the set), and a tie has to break the same way twice.
  *
- * FOUR READS RATHER THAN ONE EMBED. `cliv2_workflow_stages_in_workflow` carries
- * two foreign keys into `cliv2_workflow_stages` (`stage_id` and
- * `loop_to_stage_id`), so a nested embed of the stage document would need
- * disambiguating by constraint name — a coupling to a constraint's spelling for
- * the sake of saving a round trip on a tool call an agent makes once.
+ * SEPARATE READS RATHER THAN ONE EMBED. `cliv2_workflow_branches` carries two
+ * foreign keys into `cliv2_workflows` (`workflow_id` and `runs_workflow_id`),
+ * so a nested embed would need disambiguating by constraint name, which couples
+ * this read to a constraint's spelling for the sake of saving a round trip on a
+ * tool call an agent makes once.
  */
 export async function readWorkflow(client, workflowId) {
-    const found = await read(client.from('cliv2_workflows').select('id, name, description, ending').eq('id', workflowId), `workflow ${workflowId}`);
+    const found = await read(client.from('cliv2_workflows').select('id, name, description, ending, archived_at').eq('id', workflowId), `workflow ${workflowId}`);
     if (found.length === 0) {
         throw new Error(`could not read workflow ${workflowId}: there is no such row, or it is not yours`);
     }
     const row = found[0];
-    const [links, exits] = await Promise.all([
+    const [links, exits, branches] = await Promise.all([
         read(client.from('cliv2_workflow_stages_in_workflow').select('stage_id, position')
             .eq('workflow_id', workflowId), `the stages of workflow ${workflowId}`),
         read(client.from('cliv2_workflow_stage_exits').select('stage_id, to_stage_id, condition, position')
             .eq('workflow_id', workflowId), `the exits of workflow ${workflowId}`),
+        read(client.from('cliv2_workflow_branches').select('when_condition, runs_workflow_id, position')
+            .eq('workflow_id', workflowId), `the branches of workflow ${workflowId}`),
     ]);
     const ordered = [...links].sort((a, b) => a.position - b.position || a.stage_id.localeCompare(b.stage_id));
     const stageRows = ordered.length === 0 ? [] : await read(client.from('cliv2_workflow_stages').select('id, name, description, body')
@@ -40,6 +43,7 @@ export async function readWorkflow(client, workflowId) {
         /* Defaulted here as well as in the column, for the web reader's reason: a
            workflow written before the ending existed reads back as 'end'. */
         ending: row.ending ?? 'end',
+        archivedAt: row.archived_at ?? null,
         stages: ordered.map((link) => {
             const stage = byId.get(link.stage_id);
             /* A LISTED STAGE THAT DID NOT COME BACK IS AN ERROR, NEVER A GAP. The
@@ -64,5 +68,189 @@ export async function readWorkflow(client, workflowId) {
             toStageId: exit.to_stage_id,
             condition: exit.condition,
         })),
+        branches: [...branches]
+            .sort((a, b) => a.position - b.position || a.runs_workflow_id.localeCompare(b.runs_workflow_id))
+            .map((branch) => ({ when: branch.when_condition, runsWorkflowId: branch.runs_workflow_id })),
     };
 }
+/**
+ * Build a whole workflow in one transaction, through `cliv2_build_workflow`.
+ *
+ * ═══ THE RPC IS THE WRITER, AND THAT IS THE POINT. ═══ A workflow is a row, a
+ * row per stage, a join row per stage and a row per exit, and half of that
+ * written is not a workflow. The function is `security definer` and re-asserts
+ * the `workflow:create` grant itself, orders the stages, and lets the backward
+ * only trigger refuse a forward jump. Its errors come back verbatim behind one
+ * sentence naming what was being made, so a refusal an agent has not seen
+ * before still says which workflow failed.
+ *
+ * ═══ AND NO ABSOLUTE LOCAL PATH GOES WITH IT. ═══ `/workflows` renders every
+ * one of these strings in hosted browser JS, so the same sweep `mcp.ts` runs
+ * over its own prose runs here, before the call rather than after it.
+ */
+export async function buildWorkflow(client, input) {
+    const prose = [['name', input.name], ['description', input.description]];
+    input.stages.forEach((stage, i) => {
+        prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
+    });
+    input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));
+    for (const [field, value] of prose) {
+        const token = absolutePathToken(value);
+        if (token) {
+            throw new Error(`could not create workflow ${input.name}: ${field} contains an absolute local path ("${token}"). `
+                + 'It is rendered by hosted browser JS and must never leave this machine; name files '
+                + 'repo-relative. Nothing was written.');
+        }
+    }
+    const { data, error } = await client.rpc('cliv2_build_workflow', {
+        p_org_id: input.orgId,
+        p_name: input.name,
+        p_description: input.description,
+        p_stages: input.stages,
+        p_exits: input.exits,
+        p_branches: [],
+        p_from_agent: input.fromAgent,
+    });
+    if (error)
+        throw new Error(`could not create workflow ${input.name}: ${error.message}`);
+    if (typeof data !== 'string' || data === '') {
+        throw new Error(`could not create workflow ${input.name}: the build returned no id`);
+    }
+    return data;
+}
+/**
+ * Reword one stage: its name, one-line description, or whole document.
+ *
+ * ═══ ONE ROW, THROUGH RLS, THE WAY /workflows DOES IT. ═══ The update policy on
+ * the stage table is the `workflow_stage:update` grant, the same one the web's
+ * `updateWorkflowStage` writes through, so the agent can reword exactly what the
+ * person it runs for can. `org_id`, `created_by` and `from_agent` are not sent:
+ * the guard freezes them, and the stage stays attributed to whoever wrote it.
+ * (Ruling 40 withheld stage prose from agents; the north star of 2026-08-28
+ * grants it, with the disclosure below as the mitigation.)
+ *
+ * ═══ A STAGE IS A SHARED ROW, ═══ so the result names every other live workflow
+ * that holds it: the caller has just changed those too. Every holder is in the
+ * stage's org (the link table's cross-org guard), a caller who could update the
+ * stage holds a grant there and so is a member, and both select policies are
+ * membership, so the list is complete.
+ */
+export async function rewordStage(client, input) {
+    const prose = [
+        ['name', input.name], ['description', input.description], ['body', input.body],
+    ];
+    for (const [field, value] of prose) {
+        const token = value === undefined ? null : absolutePathToken(value);
+        if (token) {
+            throw new Error(`could not reword the stage: ${field} contains an absolute local path ("${token}"). `
+                + 'It is rendered by hosted browser JS and must never leave this machine; name files '
+                + 'repo-relative. Nothing was written.');
+        }
+    }
+    const patch = {};
+    if (input.name !== undefined)
+        patch.name = input.name;
+    if (input.description !== undefined)
+        patch.description = input.description;
+    if (input.body !== undefined)
+        patch.body = input.body;
+    const { data, error } = await client.from('cliv2_workflow_stages')
+        .update(patch).eq('id', input.stageId).select('id');
+    if (error)
+        throw new Error(`could not reword the stage: ${error.message}. Nothing was written.`);
+    if (!data || data.length === 0) {
+        throw new Error('No permission to edit this stage, or it no longer exists.');
+    }
+    /* READ AFTER THE WRITE, because these describe a change that has happened. A
+       failed disclosure read throws with its own subject, which does not claim
+       nothing was written. */
+    const links = await read(client.from('cliv2_workflow_stages_in_workflow').select('workflow_id').eq('stage_id', input.stageId), `the workflows that hold stage ${input.stageId}`);
+    const others = [...new Set(links.map((link) => link.workflow_id))].filter((id) => id !== input.workflowId);
+    if (others.length === 0)
+        return { alsoIn: [] };
+    const live = await read(client.from('cliv2_workflows').select('name').in('id', others).is('archived_at', null).order('name'), 'the other workflows that hold this stage');
+    return { alsoIn: live.map((workflow) => workflow.name) };
+}
+/**
+ * Replace a workflow's shape in one transaction, through `cliv2_edit_workflow`.
+ *
+ * ═══ THE RPC IS THE WRITER, for `buildWorkflow`'s reasons and one more. ═══ The
+ * live-run check must see every member's runs, and `cliv2_stages` is
+ * owner-scoped RLS, so only a definer function can refuse on a teammate's
+ * behalf. Its refusals come back verbatim behind one sentence naming what was
+ * being edited.
+ *
+ * ═══ BRANCHES ARE PASSED BACK AS THEY WERE READ. ═══ The RPC replaces them from
+ * `p_branches`, and nothing in v3 sets one, so the caller hands back the list
+ * `readWorkflow` read a moment before. A branch written between that read and
+ * this call is lost, which is the posture the web's `replaceStructure` records
+ * for itself.
+ *
+ * ═══ NULL NAME OR DESCRIPTION MEANS UNCHANGED, ═══ which is the RPC's own
+ * contract: an agent adding a stage does not restate a name it is not touching.
+ */
+export async function editWorkflow(client, input) {
+    const prose = [['name', input.name], ['description', input.description]];
+    input.stages.forEach((stage, i) => {
+        if ('stage_id' in stage)
+            return;
+        prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
+    });
+    input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));
+    for (const [field, value] of prose) {
+        const token = value === null ? null : absolutePathToken(value);
+        if (token) {
+            throw new Error(`could not edit the workflow: ${field} contains an absolute local path ("${token}"). `
+                + 'It is rendered by hosted browser JS and must never leave this machine; name files '
+                + 'repo-relative. Nothing was written.');
+        }
+    }
+    const { data, error } = await client.rpc('cliv2_edit_workflow', {
+        p_workflow_id: input.workflowId,
+        p_name: input.name,
+        p_description: input.description,
+        p_stages: input.stages,
+        p_exits: input.exits,
+        p_branches: input.branches.map((branch) => ({ when: branch.when, runs_workflow_id: branch.runsWorkflowId })),
+        p_from_agent: input.fromAgent,
+    });
+    if (error)
+        throw new Error(`could not edit the workflow: ${error.message}`);
+    if (typeof data !== 'number') {
+        throw new Error('the edit was applied, but the stage count did not come back. Read the workflow to see its shape.');
+    }
+    return data;
+}
+/**
+ * Copy a workflow into a new one with no runs, through `cliv2_duplicate_workflow`.
+ *
+ * ═══ THE WAY PAST A WORKFLOW IN USE. ═══ `cliv2_edit_workflow` refuses to
+ * re-shape a workflow any work item is running, and names this as the way out:
+ * the original keeps its runs, the copy takes the change.
+ *
+ * ═══ THE STAGES ARE NOT COPIED. ═══ The copy links the same stage rows (a stage
+ * is shared, ruling 6), so rewording one still rewords both; only the shape is
+ * the copy's own. Nothing is read before the call: the RPC's own refusals
+ * (archived, not found in an organization you belong to, no stages, no grant)
+ * are complete and are the words v2 agents already see, so they come back
+ * verbatim behind one sentence rather than being restated here.
+ */
+export async function duplicateWorkflow(client, input) {
+    const token = input.name === null ? null : absolutePathToken(input.name);
+    if (token) {
+        throw new Error(`could not copy the workflow: name contains an absolute local path ("${token}"). `
+            + 'It is rendered by hosted browser JS and must never leave this machine; name files '
+            + 'repo-relative. Nothing was written.');
+    }
+    const { data, error } = await client.rpc('cliv2_duplicate_workflow', {
+        p_workflow_id: input.workflowId,
+        p_name: input.name,
+        p_from_agent: input.fromAgent,
+    });
+    if (error)
+        throw new Error(`could not copy the workflow: ${error.message}`);
+    if (typeof data !== 'string' || data === '') {
+        throw new Error('the copy may have been made, but its id did not come back. Look for it on /workflows.');
+    }
+    return data;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"