futura-scion 0.2.4 → 0.2.5

package/bin/scion.js

@@ -805,10 +805,46 @@ switch (cmd || '') {
     const positional = restArgs.filter((a) => !a.startsWith('--'));
     const target = positional[0];   // output directory
     if (!target) {
-      console.error('usage: scion scaffold <template|list> <target-dir> [--name x] [--title y] [--port N] [--param k=v] [--no-verify]');
+      console.error('usage: scion scaffold <template|fullstack|list> <target-dir> [--name x] [--port N] [--concurrency N] [--no-verify] [--dry-run]');
       process.exitCode = 2;
       break;
     }
+    if (arg === 'fullstack') {
+      // COMPOSABLE CONSTRUCTION: a workflow DAG that scaffolds backend,
+      // frontend, and CLI in parallel, then wires them into one repo.
+      const { planFullstack } = await import('../src/mind/plan-fullstack.js');
+      const params = {};
+      for (const f of flags) {
+        const m = f.match(/^--([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+        if (m) params[m[1]] = m[2];
+      }
+      const manifest = planFullstack(resolve(target), {
+        name: params.name,
+        ...(params.port !== undefined ? { port: Number(params.port) } : {}),
+      });
+      if (flags.includes('--dry-run')) {
+        console.log(`fullstack plan for ${target}:`);
+        for (const t of manifest.tasks) console.log(`  ${t.id.padEnd(20)} deps: ${(t.depends_on ?? []).join(', ') || '(parallel)'}`);
+        console.log('\nrun with --approve-as <reviewer> to construct');
+        break;
+      }
+      const approveIdx = restArgs.indexOf('--approve-as');
+      const reviewer = approveIdx !== -1 ? restArgs[approveIdx + 1] : null;
+      if (!reviewer) {
+        console.error('fullstack construction is a mutating workflow — approve it: --approve-as <reviewer> (or inspect first with --dry-run)');
+        process.exitCode = 2;
+        break;
+      }
+      const { runWorkflow } = await import('../src/kernel/workflow.js');
+      const conc = Number(flags.find((f) => f.startsWith('--concurrency='))?.split('=')[1]) || 3;
+      const r = await runWorkflow(manifest, { concurrency: conc, approval: { reviewer } });
+      console.log(`fullstack ${r.status}: ${r.completed}/${r.total} steps (concurrency ${conc})`);
+      for (const t of r.tasks ?? []) {
+        if (t.status !== 'completed') console.log(`  ${t.status.toUpperCase()}: ${t.manifestId ?? t.id} ${t.error ?? ''}`);
+      }
+      if (r.status !== 'completed') process.exitCode = 1;
+      break;
+    }
     const tpl = loadTemplate(arg);
     const params = {};
     for (const f of flags) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "futura-scion",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "The fused scion of cortex-os-agent + persona: one zero-LLM-dependent agent stack — Mind proposes, Muscle executes, Gate disposes.",
   "type": "module",
   "main": "src/index.js",

package/src/kernel/safety.js

@@ -86,8 +86,12 @@ export function assertPathAllowed(p) {
     throw new Error('safety: path must be a non-empty string');
   }
   const norm = p.replace(/\\/g, '/');
+  const base = norm.split('/').pop(); // final segment decides secrets, not substrings
   for (const d of denylist()) {
-    if (norm.includes(d)) {
+    // Segment-aware matching: `.env` denies the secrets file itself, not
+    // `.env.example` or `backend-service/` (substring matching blocked the
+    // scaffolded env CONTRACT — a template file, not a secret).
+    if (d === '.env' ? base === '.env' : norm.includes(d)) {
       throw new Error(`safety: path denied by muscle.path_deny ("${d}"): ${p}`);
     }
   }

package/src/kernel/workflow.js

@@ -231,11 +231,35 @@ async function kernelCallable(fn) {
   if (fn === 'ocrImage') {
     return (args) => ocrImage(args?.image, { ...(args?.engine ? { engine: args.engine } : {}) });
   }
+  if (fn === 'scaffold') {
+    return async (args) => {
+      const { scaffold } = await import('../mind/scaffold.js');
+      const r = await scaffold(args?.template, {
+        params: args?.params ?? {},
+        ...(args?.cwd !== undefined ? { cwd: args.cwd } : {}),
+        ...(args?.verify !== undefined ? { verify: args.verify } : {}),
+      });
+      if (!r.ok) throw new Error(r.error ?? `scaffold ${args?.template} failed (gate: ${r.gate?.verified})`);
+      return { template: r.template, files: r.files, gate: r.gate?.verified ?? null };
+    };
+  }
+  if (fn === 'scaffold.file') {
+    // Wiring step: write one glue file through the transactional applier
+    // (snapshot + rollback) with the same path guardrails as any mutation.
+    return async (args) => {
+      const { transactionalApplier } = await import('./apply.js');
+      const tx = transactionalApplier({
+        files: [{ file: args?.file, content: args?.content ?? '', description: args?.description ?? `wire ${args?.file}` }],
+      });
+      const description = tx.apply();
+      return { description, file: args?.file };
+    };
+  }
   return null;
 }
 
 function callableSurface() {
-  return 'boostConsensus, ocrImage';
+  return 'boostConsensus, ocrImage, scaffold, scaffold.file';
 }
 
 async function execShellStep(step) {

package/src/mind/plan-fullstack.js

@@ -0,0 +1,164 @@
+/**
+ * mind/plan-fullstack.js — COMPOSABLE CONSTRUCTION: a fullstack scaffold is
+ * a WORKFLOW DAG (the plan-fix lineage applied to building).
+ *
+ * Wave 1 (parallel): scaffold the backend, the frontend, and the CLI into
+ * their subdirectories — three independent `scaffold` kernel calls.
+ * Wave 2 (wiring, after all of wave 1): generate the cross-component glue
+ * that only makes sense once all three exist:
+ *
+ *   - frontend/src/api.js      — a typed-ish fetch client for the backend
+ *   - README.md                — the repo-level map of all three components
+ *   - .env.example             — shared env contract (PORT for the backend)
+ *
+ * The wiring steps are shell-independent: they are emitted as additional
+ * `scaffold`-adjacent `call` steps writing files through the same
+ * transactional path the Gate judges. Resumability inherits from the
+ * workflow engine: a failed wiring step can be re-driven; completed
+ * scaffolds never re-run.
+ *
+ * @module mind/plan-fullstack
+ */
+
+'use strict';
+
+import * as trail from '../kernel/trail.js';
+
+/**
+ * Generate the fullstack workflow manifest.
+ * @param {string} targetDir — repo root to construct into
+ * @param {object} [opts] — { name?, backend?, frontend?, cli?, port? }
+ *   backend/frontend/cli: { template, params } overrides; defaults build
+ *   node-api + static-web + node-cli.
+ * @returns {object} a workflow manifest ({ name, tasks })
+ */
+export function planFullstack(targetDir, opts = {}) {
+  if (!targetDir || typeof targetDir !== 'string') {
+    throw new Error('planFullstack: targetDir is required');
+  }
+  const name = opts.name ?? targetDir.split(/[\\/]/).pop() ?? 'fullstack-app';
+  const port = String(opts.port ?? 3000);
+  const backend = { template: 'node-api', dir: 'backend', params: { name: `${name}-api`, port }, ...(opts.backend ?? {}) };
+  const frontend = { template: 'static-web', dir: 'frontend', params: { name: `${name}-web`, title: name }, ...(opts.frontend ?? {}) };
+  const cli = { template: 'node-cli', dir: 'cli', params: { name: `${name}-cli` }, ...(opts.cli ?? {}) };
+  const base = String(targetDir).replace(/\\/g, '/').replace(/\/$/, '');
+
+  const tasks = [];
+
+  // ── Wave 1: the three scaffolds, mutually independent → parallel ──
+  tasks.push(
+    { id: 'scaffold-backend', type: 'call', fn: 'scaffold', args: { template: backend.template, params: backend.params, cwd: `${base}/${backend.dir}` } },
+    { id: 'scaffold-frontend', type: 'call', fn: 'scaffold', args: { template: frontend.template, params: frontend.params, cwd: `${base}/${frontend.dir}` } },
+    { id: 'scaffold-cli', type: 'call', fn: 'scaffold', args: { template: cli.template, params: cli.params, cwd: `${base}/${cli.dir}` } },
+  );
+
+  // ── Wave 2: wiring — depends on ALL of wave 1 ──
+  tasks.push(
+    {
+      id: 'wire-frontend-api',
+      type: 'call',
+      fn: 'scaffold.file',
+      args: {
+        file: `${base}/${frontend.dir}/js/api.js`,
+        content: apiClientModule(port),
+        description: 'frontend API client for the backend',
+      },
+      depends_on: ['scaffold-backend', 'scaffold-frontend'],
+    },
+    {
+      id: 'wire-env-contract',
+      type: 'call',
+      fn: 'scaffold.file',
+      args: {
+        file: `${base}/.env.example`,
+        content: envContract(port),
+        description: 'shared env contract',
+      },
+      depends_on: ['scaffold-backend'],
+    },
+    {
+      id: 'wire-root-readme',
+      type: 'call',
+      fn: 'scaffold.file',
+      args: {
+        file: `${base}/README.md`,
+        content: rootReadme(name, { backend, frontend, cli, port }),
+        description: 'repo-level map of the three components',
+      },
+      depends_on: ['scaffold-backend', 'scaffold-frontend', 'scaffold-cli'],
+    },
+  );
+
+  const manifest = {
+    name: `fullstack-${name}`,
+    description: `Fullstack construct: ${backend.template} backend + ${frontend.template} frontend + ${cli.template} CLI, wired into one repo`,
+    tasks,
+  };
+  trail.journal('scaffold.fullstack-plan', { name, target: base, tasks: tasks.length });
+  return manifest;
+}
+
+/** The frontend's generated API client — fetch wrapper over the backend. */
+function apiClientModule(port) {
+  return `/**
+ * api.js — generated by FS fullstack scaffold. The ONLY place the frontend
+ * knows the backend's address; change API_URL here and nowhere else.
+ */
+const API_URL = 'http://localhost:${port}';
+
+async function request(path, opts = {}) {
+  const res = await fetch(\`\${API_URL}\${path}\`, {
+    headers: { 'content-type': 'application/json' },
+    ...opts,
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(body.error ?? \`HTTP \${res.status}\`);
+  return body;
+}
+
+export const api = {
+  health: () => request('/health'),
+  listItems: () => request('/items'),
+  addItem: (title) => request('/items', { method: 'POST', body: JSON.stringify({ title }) }),
+};
+`;
+}
+
+/** The shared env contract. */
+function envContract(port) {
+  return `# Generated by FS fullstack scaffold — the env contract shared by all components.
+PORT=${port}
+NODE_ENV=development
+`;
+}
+
+/** The repo-level README. */
+function rootReadme(name, { backend, frontend, cli, port }) {
+  return `# ${name}
+
+Fullstack repo constructed by FS scaffold — three gate-verified components
+wired into one tree. Every file passed the stack's verifier recipe (real
+exit codes) before this run reported success.
+
+## Layout
+
+| Component | Template | Location |
+|---|---|---|
+| Backend API | \`${backend.template}\` | \`${backend.dir}/\` — serves on :${port} |
+| Frontend | \`${frontend.template}\` | \`${frontend.dir}/\` — open \`index.html\` |
+| CLI | \`${cli.template}\` | \`${cli.dir}/\` |
+
+## Run
+
+\`\`\`bash
+cd ${backend.dir} && npm install && npm start   # API on :${port}
+cd ${frontend.dir}                               # open index.html (js/api.js talks to :${port})
+cd ${cli.dir} && npm install && npm test
+\`\`\`
+
+## Contract
+
+- The frontend's \`${frontend.dir}/js/api.js\` is the single seam to the backend.
+- \`.env.example\` is the shared environment contract.
+`;
+}