@ctrl-spc/cs 0.7.3 → 0.7.5

package/dist/steps.js

@@ -0,0 +1,168 @@
+import { absolutePathToken } from './local-paths.js';
+export const STEP_STATUSES = ['pending', 'in_progress', 'blocked', 'interrupted', 'done'];
+const STAGE_COLUMNS = 'id, work_item_id, title, position, source_kind, source_label, source_ref, source_workflow_ref';
+const STEP_COLUMNS = 'id, stage_id, title, charter, next_action, status, position, source_kind, source_label, source_ref';
+async function read(query, subject) {
+    const { data, error } = await query;
+    if (error)
+        throw new Error(`could not read ${subject}: ${error.message}`);
+    return data ?? [];
+}
+const stageOf = (row) => ({
+    id: row.id,
+    workItemId: row.work_item_id,
+    title: row.title,
+    position: row.position,
+    sourceKind: row.source_kind,
+    sourceLabel: row.source_label,
+    sourceRef: row.source_ref,
+    sourceWorkflowRef: row.source_workflow_ref,
+});
+const stepOf = (row) => ({
+    id: row.id,
+    stageId: row.stage_id,
+    title: row.title,
+    charter: row.charter,
+    nextAction: row.next_action,
+    status: row.status,
+    position: row.position,
+    sourceKind: row.source_kind,
+    sourceLabel: row.source_label,
+    sourceRef: row.source_ref,
+});
+/** Refuse prose that carries an absolute local path, before it is written. */
+function sweep(action, prose) {
+    for (const [field, value] of prose) {
+        const token = value === undefined ? null : absolutePathToken(value);
+        if (token) {
+            throw new Error(`could not ${action}: ${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.');
+        }
+    }
+}
+/** The stages on one work item, in the order they are worked. */
+export async function stagesOnItem(client, workItemId) {
+    const rows = await read(client.from('cliv2_stages').select(STAGE_COLUMNS).eq('work_item_id', workItemId)
+        .order('position', { ascending: true }).order('created_at', { ascending: true }), `the stages of work item ${workItemId}`);
+    return rows.map(stageOf);
+}
+/** One stage by id, or null when there is no such row or it is not the caller's. */
+export async function stageById(client, stageId) {
+    const rows = await read(client.from('cliv2_stages').select(STAGE_COLUMNS).eq('id', stageId), `stage ${stageId}`);
+    return rows.length === 0 ? null : stageOf(rows[0]);
+}
+/** One step by id, or null when there is no such row or it is not the caller's. */
+export async function stepById(client, stepId) {
+    const rows = await read(client.from('cliv2_steps').select(STEP_COLUMNS).eq('id', stepId), `step ${stepId}`);
+    return rows.length === 0 ? null : stepOf(rows[0]);
+}
+/**
+ * Put a workflow's stages on a work item, once.
+ *
+ * `cliv2_start_workflow` is the one guard: it refuses a workflow already on
+ * the item, atomically, with "already started". That refusal is turned into a
+ * calm `{ started: false }` here, because an owner restarted at a stage
+ * boundary calls this again and must not read its own earlier success as a
+ * failure. Any other refusal comes back verbatim.
+ */
+export async function startWorkflowOnItem(client, workItemId, workflowId) {
+    const { data, error } = await client.rpc('cliv2_start_workflow', {
+        p_work_item_id: workItemId,
+        p_workflow_id: workflowId,
+    });
+    if (error) {
+        if (/already started/i.test(error.message)) {
+            const existing = (await stagesOnItem(client, workItemId))
+                .filter((stage) => stage.sourceWorkflowRef === workflowId);
+            return { started: false, stages: existing.length };
+        }
+        throw new Error(`could not start workflow ${workflowId} on work item ${workItemId}: ${error.message}. `
+            + 'Nothing was written.');
+    }
+    return { started: true, stages: Number(data) };
+}
+/** The whole spine of one work item plus the one shared "up next". */
+export async function listSteps(client, workItemId) {
+    const stages = await stagesOnItem(client, workItemId);
+    const steps = stages.length === 0 ? [] : await read(client.from('cliv2_steps').select(STEP_COLUMNS).in('stage_id', stages.map((stage) => stage.id))
+        .order('position', { ascending: true }).order('created_at', { ascending: true }), `the steps of work item ${workItemId}`);
+    const { data: upNext, error } = await client.rpc('cliv2_steps_up_next', { p_work_item_id: workItemId });
+    if (error)
+        throw new Error(`could not read what is up next on work item ${workItemId}: ${error.message}`);
+    return {
+        stages: stages.map((stage) => ({
+            ...stage,
+            steps: steps.filter((row) => row.stage_id === stage.id).map(stepOf),
+        })),
+        upNext,
+    };
+}
+/**
+ * Record one step inside a stage. Provenance is COPIED FROM THE STAGE, never
+ * chosen by the caller: a step under a workflow stage says which workflow, and
+ * a step under a plan stage says which plan, and an agent cannot mislabel one.
+ */
+export async function createStep(client, stage, input) {
+    const action = `record the step "${input.title}"`;
+    for (const [field, value] of [['title', input.title], ['charter', input.charter], ['next_action', input.nextAction]]) {
+        if (value.trim() === '')
+            throw new Error(`could not ${action}: ${field} is blank. Nothing was written.`);
+    }
+    if (!Number.isInteger(input.position)) {
+        throw new Error(`could not ${action}: position must be a whole number. Nothing was written.`);
+    }
+    sweep(action, [['title', input.title], ['charter', input.charter], ['next_action', input.nextAction]]);
+    const rows = await read(client.from('cliv2_steps').insert({
+        stage_id: stage.id,
+        title: input.title,
+        charter: input.charter,
+        next_action: input.nextAction,
+        position: input.position,
+        source_kind: stage.sourceKind,
+        source_label: stage.sourceLabel,
+        source_ref: stage.sourceRef,
+    }).select('id'), `the step just written under stage ${stage.id}`);
+    if (rows.length === 0)
+        throw new Error(`could not ${action}: the write returned no row.`);
+    return { id: rows[0].id };
+}
+/**
+ * Change a step's living fields. The database grants update on exactly these
+ * four columns, so a stage, position or provenance change is refused there
+ * whatever a caller sends; this refuses the two things the database cannot see:
+ * a call that changes nothing, and a blank string offered as a way to clear.
+ */
+export async function updateStep(client, step, changes) {
+    const action = `update the step "${step.title}"`;
+    const patch = {};
+    const updated = [];
+    const consider = (field, next, current) => {
+        if (next === undefined)
+            return;
+        if (next.trim() === '') {
+            throw new Error(`could not ${action}: ${field} is blank. A field cannot be cleared; nothing was written.`);
+        }
+        if (next === current)
+            return;
+        patch[field] = next;
+        updated.push(field);
+    };
+    if (changes.status !== undefined && !STEP_STATUSES.includes(changes.status)) {
+        throw new Error(`could not ${action}: "${changes.status}" is not a status. Use one of ${STEP_STATUSES.join(', ')}. `
+            + 'Nothing was written.');
+    }
+    consider('title', changes.title, step.title);
+    consider('charter', changes.charter, step.charter);
+    consider('next_action', changes.nextAction, step.nextAction);
+    consider('status', changes.status, step.status);
+    if (updated.length === 0) {
+        throw new Error(`could not ${action}: nothing would change. Nothing was written.`);
+    }
+    sweep(action, [['title', changes.title], ['charter', changes.charter], ['next_action', changes.nextAction]]);
+    const rows = await read(client.from('cliv2_steps').update(patch).eq('id', step.id).select('id'), `the step just updated (${step.id})`);
+    if (rows.length === 0) {
+        throw new Error(`could not ${action}: the update matched no row, so nothing was written.`);
+    }
+    return { id: step.id, updated: updated.sort() };
+}

package/dist/supabase.js

@@ -58,11 +58,38 @@ const retryingFetch = async (input, init) => {
  * lifetime: `autoRefreshToken: true` (v1 had it false with no refresh loop, so
  * after an hour every write 401'd silently) and the retrying fetch above.
  * Rotated tokens are written straight back to disk via onAuthStateChange.
+ *
+ * Pass `{ refreshing: false }` for a client that can never rotate the stored
+ * refresh token, for a caller that shares session.json with another process:
+ * two processes refreshing the same token family revoke it for both.
  */
-export async function getClient() {
+export async function getClient({ refreshing = true } = {}) {
     const stored = readSession();
-    if (!stored?.access_token || !stored?.refresh_token)
+    // The refreshing path still requires both, exactly as today. The
+    // non-refreshing one is never handed a refresh token, so it must not demand
+    // one: requiring it would refuse a session this client can legitimately use.
+    if (!stored?.access_token)
+        throw new NotLoggedIn();
+    if (refreshing && !stored?.refresh_token)
         throw new NotLoggedIn();
+    /* ═══ NOT REFRESHING MEANS NEVER HANDED THE REFRESH TOKEN. ═══ Not merely
+       `autoRefreshToken: false`: auth-js refreshes inside `setSession` whenever
+       the access token has already expired, regardless of that flag
+       (`GoTrueClient.js:2994`). A client never given the refresh token has
+       nothing to rotate, which is the only guarantee that holds. Two processes
+       rotating one `session.json` revoke the family for both.
+  
+       An already-expired token is refused here rather than left to fail at the
+       first query, so callers keep the `NotLoggedIn` boundary they have today.
+       Same pattern as `scripts/prove-scope-history.mjs:34-41`. */
+    if (!refreshing) {
+        if (accessTokenExpired(stored.access_token))
+            throw new NotLoggedIn();
+        return createClient(SUPABASE_URL, SUPABASE_KEY, {
+            auth: { persistSession: false, autoRefreshToken: false },
+            global: { fetch: retryingFetch, headers: { Authorization: `Bearer ${stored.access_token}` } },
+        });
+    }
     const client = createClient(SUPABASE_URL, SUPABASE_KEY, {
         auth: { persistSession: false, autoRefreshToken: true },
         global: { fetch: retryingFetch },
@@ -84,3 +111,17 @@ export async function getClient() {
     }
     return client;
 }
+/** Whether a stored access token's own `exp` claim has already passed. A token
+ *  this process cannot parse is treated as unusable rather than trusted: the
+ *  caller's next request would 401 anyway, and `NotLoggedIn` is the honest
+ *  answer at the boundary rather than a raw SyntaxError from the middle of a
+ *  request handler. Exported so a test can pass a string and nothing else. */
+export function accessTokenExpired(token) {
+    try {
+        const claims = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString());
+        return typeof claims.exp !== 'number' || claims.exp * 1000 <= Date.now();
+    }
+    catch {
+        return true;
+    }
+}

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.5",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"