switchboard-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/node_modules/@switchboard/projections/node_modules/yaml/dist/visit.js

@@ -0,0 +1,236 @@
+'use strict';
+
+var identity = require('./nodes/identity.js');
+
+const BREAK = Symbol('break visit');
+const SKIP = Symbol('skip children');
+const REMOVE = Symbol('remove node');
+/**
+ * Apply a visitor to an AST node or document.
+ *
+ * Walks through the tree (depth-first) starting from `node`, calling a
+ * `visitor` function with three arguments:
+ *   - `key`: For sequence values and map `Pair`, the node's index in the
+ *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
+ *     `null` for the root node.
+ *   - `node`: The current node.
+ *   - `path`: The ancestry of the current node.
+ *
+ * The return value of the visitor may be used to control the traversal:
+ *   - `undefined` (default): Do nothing and continue
+ *   - `visit.SKIP`: Do not visit the children of this node, continue with next
+ *     sibling
+ *   - `visit.BREAK`: Terminate traversal completely
+ *   - `visit.REMOVE`: Remove the current node, then continue with the next one
+ *   - `Node`: Replace the current node, then continue by visiting it
+ *   - `number`: While iterating the items of a sequence or map, set the index
+ *     of the next step. This is useful especially if the index of the current
+ *     node has changed.
+ *
+ * If `visitor` is a single function, it will be called with all values
+ * encountered in the tree, including e.g. `null` values. Alternatively,
+ * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
+ * `Alias` and `Scalar` node. To define the same visitor function for more than
+ * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
+ * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
+ * specific defined one will be used for each node.
+ */
+function visit(node, visitor) {
+    const visitor_ = initVisitor(visitor);
+    if (identity.isDocument(node)) {
+        const cd = visit_(null, node.contents, visitor_, Object.freeze([node]));
+        if (cd === REMOVE)
+            node.contents = null;
+    }
+    else
+        visit_(null, node, visitor_, Object.freeze([]));
+}
+// Without the `as symbol` casts, TS declares these in the `visit`
+// namespace using `var`, but then complains about that because
+// `unique symbol` must be `const`.
+/** Terminate visit traversal completely */
+visit.BREAK = BREAK;
+/** Do not visit the children of the current node */
+visit.SKIP = SKIP;
+/** Remove the current node */
+visit.REMOVE = REMOVE;
+function visit_(key, node, visitor, path) {
+    const ctrl = callVisitor(key, node, visitor, path);
+    if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
+        replaceNode(key, path, ctrl);
+        return visit_(key, ctrl, visitor, path);
+    }
+    if (typeof ctrl !== 'symbol') {
+        if (identity.isCollection(node)) {
+            path = Object.freeze(path.concat(node));
+            for (let i = 0; i < node.items.length; ++i) {
+                const ci = visit_(i, node.items[i], visitor, path);
+                if (typeof ci === 'number')
+                    i = ci - 1;
+                else if (ci === BREAK)
+                    return BREAK;
+                else if (ci === REMOVE) {
+                    node.items.splice(i, 1);
+                    i -= 1;
+                }
+            }
+        }
+        else if (identity.isPair(node)) {
+            path = Object.freeze(path.concat(node));
+            const ck = visit_('key', node.key, visitor, path);
+            if (ck === BREAK)
+                return BREAK;
+            else if (ck === REMOVE)
+                node.key = null;
+            const cv = visit_('value', node.value, visitor, path);
+            if (cv === BREAK)
+                return BREAK;
+            else if (cv === REMOVE)
+                node.value = null;
+        }
+    }
+    return ctrl;
+}
+/**
+ * Apply an async visitor to an AST node or document.
+ *
+ * Walks through the tree (depth-first) starting from `node`, calling a
+ * `visitor` function with three arguments:
+ *   - `key`: For sequence values and map `Pair`, the node's index in the
+ *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
+ *     `null` for the root node.
+ *   - `node`: The current node.
+ *   - `path`: The ancestry of the current node.
+ *
+ * The return value of the visitor may be used to control the traversal:
+ *   - `Promise`: Must resolve to one of the following values
+ *   - `undefined` (default): Do nothing and continue
+ *   - `visit.SKIP`: Do not visit the children of this node, continue with next
+ *     sibling
+ *   - `visit.BREAK`: Terminate traversal completely
+ *   - `visit.REMOVE`: Remove the current node, then continue with the next one
+ *   - `Node`: Replace the current node, then continue by visiting it
+ *   - `number`: While iterating the items of a sequence or map, set the index
+ *     of the next step. This is useful especially if the index of the current
+ *     node has changed.
+ *
+ * If `visitor` is a single function, it will be called with all values
+ * encountered in the tree, including e.g. `null` values. Alternatively,
+ * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
+ * `Alias` and `Scalar` node. To define the same visitor function for more than
+ * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
+ * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
+ * specific defined one will be used for each node.
+ */
+async function visitAsync(node, visitor) {
+    const visitor_ = initVisitor(visitor);
+    if (identity.isDocument(node)) {
+        const cd = await visitAsync_(null, node.contents, visitor_, Object.freeze([node]));
+        if (cd === REMOVE)
+            node.contents = null;
+    }
+    else
+        await visitAsync_(null, node, visitor_, Object.freeze([]));
+}
+// Without the `as symbol` casts, TS declares these in the `visit`
+// namespace using `var`, but then complains about that because
+// `unique symbol` must be `const`.
+/** Terminate visit traversal completely */
+visitAsync.BREAK = BREAK;
+/** Do not visit the children of the current node */
+visitAsync.SKIP = SKIP;
+/** Remove the current node */
+visitAsync.REMOVE = REMOVE;
+async function visitAsync_(key, node, visitor, path) {
+    const ctrl = await callVisitor(key, node, visitor, path);
+    if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
+        replaceNode(key, path, ctrl);
+        return visitAsync_(key, ctrl, visitor, path);
+    }
+    if (typeof ctrl !== 'symbol') {
+        if (identity.isCollection(node)) {
+            path = Object.freeze(path.concat(node));
+            for (let i = 0; i < node.items.length; ++i) {
+                const ci = await visitAsync_(i, node.items[i], visitor, path);
+                if (typeof ci === 'number')
+                    i = ci - 1;
+                else if (ci === BREAK)
+                    return BREAK;
+                else if (ci === REMOVE) {
+                    node.items.splice(i, 1);
+                    i -= 1;
+                }
+            }
+        }
+        else if (identity.isPair(node)) {
+            path = Object.freeze(path.concat(node));
+            const ck = await visitAsync_('key', node.key, visitor, path);
+            if (ck === BREAK)
+                return BREAK;
+            else if (ck === REMOVE)
+                node.key = null;
+            const cv = await visitAsync_('value', node.value, visitor, path);
+            if (cv === BREAK)
+                return BREAK;
+            else if (cv === REMOVE)
+                node.value = null;
+        }
+    }
+    return ctrl;
+}
+function initVisitor(visitor) {
+    if (typeof visitor === 'object' &&
+        (visitor.Collection || visitor.Node || visitor.Value)) {
+        return Object.assign({
+            Alias: visitor.Node,
+            Map: visitor.Node,
+            Scalar: visitor.Node,
+            Seq: visitor.Node
+        }, visitor.Value && {
+            Map: visitor.Value,
+            Scalar: visitor.Value,
+            Seq: visitor.Value
+        }, visitor.Collection && {
+            Map: visitor.Collection,
+            Seq: visitor.Collection
+        }, visitor);
+    }
+    return visitor;
+}
+function callVisitor(key, node, visitor, path) {
+    if (typeof visitor === 'function')
+        return visitor(key, node, path);
+    if (identity.isMap(node))
+        return visitor.Map?.(key, node, path);
+    if (identity.isSeq(node))
+        return visitor.Seq?.(key, node, path);
+    if (identity.isPair(node))
+        return visitor.Pair?.(key, node, path);
+    if (identity.isScalar(node))
+        return visitor.Scalar?.(key, node, path);
+    if (identity.isAlias(node))
+        return visitor.Alias?.(key, node, path);
+    return undefined;
+}
+function replaceNode(key, path, node) {
+    const parent = path[path.length - 1];
+    if (identity.isCollection(parent)) {
+        parent.items[key] = node;
+    }
+    else if (identity.isPair(parent)) {
+        if (key === 'key')
+            parent.key = node;
+        else
+            parent.value = node;
+    }
+    else if (identity.isDocument(parent)) {
+        parent.contents = node;
+    }
+    else {
+        const pt = identity.isAlias(parent) ? 'alias' : 'scalar';
+        throw new Error(`Cannot replace node with ${pt} parent`);
+    }
+}
+
+exports.visit = visit;
+exports.visitAsync = visitAsync;

package/node_modules/@switchboard/projections/node_modules/yaml/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "yaml",
+  "version": "2.8.3",
+  "license": "ISC",
+  "author": "Eemeli Aro <eemeli@gmail.com>",
+  "funding": "https://github.com/sponsors/eemeli",
+  "repository": "github:eemeli/yaml",
+  "description": "JavaScript parser and stringifier for YAML",
+  "keywords": [
+    "YAML",
+    "parser",
+    "stringifier"
+  ],
+  "homepage": "https://eemeli.org/yaml/",
+  "files": [
+    "browser/",
+    "dist/",
+    "util.js"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "bin": "./bin.mjs",
+  "browser": {
+    "./dist/index.js": "./browser/index.js",
+    "./dist/util.js": "./browser/dist/util.js",
+    "./util.js": "./browser/dist/util.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "default": "./browser/index.js"
+    },
+    "./package.json": "./package.json",
+    "./util": {
+      "types": "./dist/util.d.ts",
+      "node": "./dist/util.js",
+      "default": "./browser/dist/util.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:node && npm run build:browser",
+    "build:browser": "rollup -c config/rollup.browser-config.mjs",
+    "build:node": "rollup -c config/rollup.node-config.mjs",
+    "clean": "git clean -fdxe node_modules",
+    "lint": "eslint config/ src/",
+    "prettier": "prettier --write .",
+    "prestart": "rollup --sourcemap -c config/rollup.node-config.mjs",
+    "start": "node --enable-source-maps -i -e 'YAML=require(\"./dist/index.js\");const{parse,parseDocument,parseAllDocuments}=YAML'",
+    "test": "jest --config config/jest.config.js",
+    "test:all": "npm test && npm run test:types && npm run test:dist && npm run test:dist:types",
+    "test:browsers": "cd playground && npm test",
+    "test:dist": "npm run build:node && jest --config config/jest.config.js",
+    "test:dist:types": "tsc --allowJs --moduleResolution node --noEmit --target es5 dist/index.js",
+    "test:types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "docs:install": "cd docs-slate && bundle install",
+    "predocs:deploy": "node docs/prepare-docs.mjs",
+    "docs:deploy": "cd docs-slate && ./deploy.sh",
+    "predocs": "node docs/prepare-docs.mjs",
+    "docs": "cd docs-slate && bundle exec middleman server",
+    "preversion": "npm test && npm run build",
+    "prepublishOnly": "npm run clean && npm test && npm run build"
+  },
+  "browserslist": "defaults, not ie 11",
+  "prettier": {
+    "arrowParens": "avoid",
+    "semi": false,
+    "singleQuote": true,
+    "trailingComma": "none"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.12.10",
+    "@babel/plugin-transform-typescript": "^7.12.17",
+    "@babel/preset-env": "^7.12.11",
+    "@eslint/js": "^9.9.1",
+    "@rollup/plugin-babel": "^6.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-typescript": "^12.1.1",
+    "@types/jest": "^29.2.4",
+    "@types/node": "^20.11.20",
+    "babel-jest": "^29.0.1",
+    "eslint": "^9.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "fast-check": "^2.12.0",
+    "jest": "^29.0.1",
+    "jest-resolve": "^29.7.0",
+    "jest-ts-webcompat-resolver": "^1.0.0",
+    "prettier": "^3.0.2",
+    "rollup": "^4.12.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.4.0"
+  },
+  "engines": {
+    "node": ">= 14.6"
+  }
+}

package/node_modules/@switchboard/projections/node_modules/yaml/util.js

@@ -0,0 +1,2 @@
+// Re-exporter for Node.js < 12.16.0
+module.exports = require('./dist/util.js')

package/node_modules/@switchboard/projections/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@switchboard/projections",
+  "version": "0.1.0-alpha.1",
+  "description": "Switchboard projections — SBX bundle generation and surface-specific dispatch formatting",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "build": "tsc --outDir dist",
+    "lint": "echo 'linted projections'",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@switchboard/core": "workspace:*",
+    "yaml": "^2.7.0"
+  }
+}

package/node_modules/@switchboard/projections/src/claude/index.ts

@@ -0,0 +1,164 @@
+import {
+  runtimePackSchema,
+  type HandoffRecord,
+  type ProjectContract,
+  type RuntimePack,
+  type SurfacePlaybook,
+  type WorkingState,
+} from "@switchboard/core";
+
+type ClaudeProjectionInput = {
+  contract: ProjectContract;
+  current: WorkingState;
+  spec_markdown: string;
+  handoff: HandoffRecord;
+  playbook: SurfacePlaybook;
+};
+
+function renderRoot(input: ClaudeProjectionInput) {
+  return `# CLAUDE.md
+
+This is a Switchboard-generated runtime projection for the active loop.
+It is not canonical truth. Canonical truth remains in .switchboard/ and ${input.current.primary_artifact_ref}.
+
+## Active mission
+
+- Project: ${input.contract.title}
+- Objective: ${input.handoff.loop.objective}
+- Return when: ${input.handoff.loop.return_when}
+- Fallback surface: ${input.handoff.loop.fallback_surface}
+
+## Working stance
+
+- Stay inside scope in.
+- Respect scope out.
+- Verify before claiming completion.
+- Return immediately if blocker escalation conditions fire.
+`;
+}
+
+function renderProjectRule(input: ClaudeProjectionInput) {
+  return `# Project Boundary
+
+- Canonical truth lives in .switchboard/ and ${input.current.primary_artifact_ref}.
+- This projection is ephemeral and launch-time only.
+- Do not widen the product into orchestration controls, workers, or runtime infrastructure.
+- Keep the active slice bounded and coherent.
+`;
+}
+
+function renderActiveLoopRule(input: ClaudeProjectionInput) {
+  return `# Active Loop
+
+## Objective
+
+${input.handoff.loop.objective}
+
+## Scope In
+
+- ${input.handoff.loop.scope_in.join("\n- ")}
+
+## Scope Out
+
+- ${input.handoff.loop.scope_out.join("\n- ")}
+
+## Done-When
+
+- ${input.handoff.loop.done_when.join("\n- ")}
+
+## Success Criteria
+
+- ${input.handoff.loop.success_criteria.join("\n- ")}
+
+## Verify With
+
+- ${input.handoff.loop.verify_with.join("\n- ")}
+
+## Expected Artifacts
+
+- ${input.handoff.loop.expected_artifacts.join("\n- ")}
+
+## Execution Shape
+
+${input.handoff.loop.execution_shape}
+`;
+}
+
+function renderReturnContractRule(input: ClaudeProjectionInput) {
+  return `# Return Contract
+
+## Return When
+
+${input.handoff.loop.return_when}
+
+## Blocker Escalation
+
+- ${input.handoff.loop.blocker_escalation.join("\n- ")}
+
+## Surface Notes
+
+- ${input.playbook.notes.join("\n- ")}
+
+## Required Return Fields (SB_RETURN.yaml)
+
+Your return MUST be a valid YAML file with ALL of these fields:
+
+- handoff_id: "${input.handoff.handoff_id}" (exact — copy this value)
+- surface_used: "${input.handoff.surface}" (exact — copy this value)
+- objective_attempted: "${input.handoff.loop.objective}" (exact — copy this value)
+- status: done | partial | blocked
+- objective_met: yes | no | partial
+- done_when_met: yes | no | partial
+- summary: (what you did — required, non-empty)
+- changed_files: [list of files touched]
+- decisions_made: [list of decisions]
+- blockers: [list of blockers, empty if none]
+- escalations: [list of escalations, empty if none]
+- evidence: [list of evidence items — required if claiming done]
+- success_criteria_met: [list of criteria met — required if claiming done]
+- verification_run: [list of verification checks run — required if claiming done]
+- artifacts_created: [list of artifacts]
+- recommended_next_step: (what should happen next — required, non-empty)
+
+IMPORTANT: If status is "done" and objective_met is "yes", you MUST provide
+at least one item in evidence or verification_run. Empty evidence with done
+status will be rejected by the ingest validator.
+`;
+}
+
+export function generateClaudeRuntimeProjection(input: ClaudeProjectionInput): RuntimePack {
+  return runtimePackSchema.parse({
+    pack_name: `${input.contract.project_id}-${input.handoff.handoff_id}-claude-runtime.zip`,
+    files: [
+      {
+        path: "CLAUDE.md",
+        content: renderRoot(input),
+      },
+      {
+        path: ".claude/rules/project.md",
+        content: renderProjectRule(input),
+      },
+      {
+        path: ".claude/rules/active-loop.md",
+        content: renderActiveLoopRule(input),
+      },
+      {
+        path: ".claude/rules/return-contract.md",
+        content: renderReturnContractRule(input),
+      },
+      {
+        path: ".claude/settings.example.json",
+        content: JSON.stringify(
+          {
+            switchboard_projection: "example-only",
+            note: "This file is a projection, not canonical truth.",
+            mission_boundary: input.handoff.loop.objective,
+            return_when: input.handoff.loop.return_when,
+          },
+          null,
+          2,
+        ),
+      },
+    ],
+  });
+}

package/node_modules/@switchboard/projections/src/index.ts

@@ -0,0 +1,160 @@
+import YAML from "yaml";
+import {
+  createReturnTemplate,
+  type HandoffRecord,
+  type ProjectContract,
+  type ReturnReport,
+  type SbxBundle,
+  type WorkingState,
+  sbxBundleSchema,
+} from "@switchboard/core";
+
+export * from "./claude";
+
+type BundleInput = {
+  contract: ProjectContract;
+  current: WorkingState;
+  spec_markdown: string;
+  handoff: HandoffRecord;
+  latest_return?: ReturnReport | null;
+};
+
+function renderIndex(input: BundleInput) {
+  const fileLines = ["SB_INDEX.md", "SB_SPEC.md", "SB_TASK.md", "SB_STATE.yaml", "SB_RETURN.yaml"];
+
+  if (input.latest_return || input.current.open_questions.length > 0 || input.current.latest_blockers.length > 0) {
+    fileLines.push("SB_APPENDIX.md");
+  }
+
+  return `# SBX Bundle
+
+## Project
+
+- Title: ${input.contract.title}
+- Project ID: ${input.contract.project_id}
+- Surface: ${input.handoff.surface}
+- Handoff ID: ${input.handoff.handoff_id}
+- Launch readiness: ${input.handoff.readiness.status}
+- Execution shape: ${input.handoff.loop.execution_shape}
+
+## Objective
+
+${input.handoff.loop.objective}
+
+## Files
+
+- ${fileLines.join("\n- ")}
+`;
+}
+
+function renderTask(input: BundleInput) {
+  return `# SB_TASK
+
+## Objective
+
+${input.handoff.loop.objective}
+
+## Scope In
+
+- ${input.handoff.loop.scope_in.join("\n- ")}
+
+## Scope Out
+
+- ${input.handoff.loop.scope_out.join("\n- ")}
+
+## Done-When
+
+- ${input.handoff.loop.done_when.join("\n- ")}
+
+## Success Criteria
+
+- ${input.handoff.loop.success_criteria.join("\n- ")}
+
+## Verify With
+
+- ${input.handoff.loop.verify_with.join("\n- ")}
+
+## Return When
+
+${input.handoff.loop.return_when}
+
+## Blocker Escalation
+
+- ${input.handoff.loop.blocker_escalation.join("\n- ")}
+
+## Expected Artifacts
+
+- ${input.handoff.loop.expected_artifacts.join("\n- ")}
+
+## Fallback Surface
+
+${input.handoff.loop.fallback_surface}
+
+## Launch Readiness
+
+${input.handoff.readiness.status}
+`;
+}
+
+function renderAppendix(input: BundleInput) {
+  const sections: string[] = [];
+
+  if (input.current.open_questions.length > 0) {
+    sections.push(`## Open Questions\n\n- ${input.current.open_questions.join("\n- ")}`);
+  }
+
+  if (input.current.latest_blockers.length > 0) {
+    sections.push(`## Latest Blockers\n\n- ${input.current.latest_blockers.join("\n- ")}`);
+  }
+
+  if (input.latest_return) {
+    sections.push(`## Latest Return Summary\n\n${input.latest_return.summary}`);
+  }
+
+  return sections.join("\n\n");
+}
+
+export function generateSbxBundle(input: BundleInput): SbxBundle {
+  const returnTemplate = createReturnTemplate(input.handoff);
+  const files = [
+    {
+      path: "SB_INDEX.md",
+      content: renderIndex(input),
+    },
+    {
+      path: "SB_SPEC.md",
+      content: input.spec_markdown.trim(),
+    },
+    {
+      path: "SB_TASK.md",
+      content: renderTask(input),
+    },
+    {
+      path: "SB_STATE.yaml",
+      content: YAML.stringify({
+        contract: input.contract,
+        current: input.current,
+        loop: input.handoff.loop,
+      }).trim(),
+    },
+    {
+      path: "SB_RETURN.yaml",
+      content: YAML.stringify(returnTemplate).trim(),
+    },
+  ];
+
+  const appendix = renderAppendix(input).trim();
+
+  if (appendix) {
+    files.push({
+      path: "SB_APPENDIX.md",
+      content: `# SB_APPENDIX\n\n${appendix}`,
+    });
+  }
+
+  return sbxBundleSchema.parse({
+    bundle_name: `${input.contract.project_id}-${input.handoff.handoff_id}.sbx.zip`,
+    launch_prompt: `Use this SBX bundle in ${input.handoff.surface}. Execute only the loop scope in, respect scope out, verify before claiming completion, and complete SB_RETURN.yaml before returning.`,
+    files,
+  });
+}