npm - @structor-dev/cli - Versions diffs - 0.1.0 - Mend

@structor-dev/cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/LICENSE +21 -0
package/README.md +405 -0
package/bin/structor.mjs +576 -0
package/docs/INIT.md +109 -0
package/docs/adr/0001-default-generated-repo-name.md +9 -0
package/docs/issues/0001-structor-doctor.md +39 -0
package/examples/frontend-backend/harness.config.json +35 -0
package/examples/openai-and-anthropic/harness.config.json +28 -0
package/examples/single-repo/harness.config.json +26 -0
package/harness.config.example.json +38 -0
package/package.json +58 -0
package/schemas/contract-manifest.schema.json +18 -0
package/schemas/harness-config.schema.json +85 -0
package/schemas/task-brief.schema.json +37 -0
package/scripts/check-config.mjs +76 -0
package/scripts/check-contract-manifests.mjs +85 -0
package/scripts/check-model-overlays.mjs +30 -0
package/scripts/check-placeholders.mjs +48 -0
package/scripts/check-task-template.mjs +53 -0
package/scripts/check-template-files.mjs +110 -0
package/scripts/init-harness.mjs +270 -0
package/scripts/lib.mjs +190 -0
package/scripts/smoke-template.mjs +309 -0
package/scripts/validate-governance.mjs +3 -0
package/scripts/validate-template.mjs +16 -0
package/template/.claude/CLAUDE.md.tpl +12 -0
package/template/.claude/rules/harness-client-surfaces.md.tpl +20 -0
package/template/.claude/settings.json.tpl +10 -0
package/template/.codex/hooks.json.tpl +77 -0
package/template/AGENTS.md.tpl +22 -0
package/template/CLAUDE.md.tpl +16 -0
package/template/README.md.tpl +109 -0
package/template/ai/AGENT-GARBAGE-COLLECTION.md.tpl +18 -0
package/template/ai/AGENTS.md.tpl +36 -0
package/template/ai/ARCHITECTURE.md.tpl +35 -0
package/template/ai/CODEX-HOOKS.md.tpl +23 -0
package/template/ai/DECISIONS.md.tpl +22 -0
package/template/ai/DESIGN.md.tpl +22 -0
package/template/ai/HARNESS-ENGINEERING.md.tpl +107 -0
package/template/ai/HARNESS.md.tpl +53 -0
package/template/ai/HUB.md.tpl +53 -0
package/template/ai/PRODUCT-SUMMARY.md.tpl +28 -0
package/template/ai/PRODUCT.md.tpl +32 -0
package/template/ai/QUALITY.md.tpl +37 -0
package/template/ai/READINESS.md.tpl +39 -0
package/template/ai/RUNNER-READINESS.md.tpl +14 -0
package/template/ai/RUNNER-SAFETY.md.tpl +21 -0
package/template/ai/VERSIONING.md.tpl +16 -0
package/template/ai/WORKFLOW.md.tpl +42 -0
package/template/ai/context.md.tpl +17 -0
package/template/ai/contracts/README.md.tpl +23 -0
package/template/ai/contracts/api-boundary.contract.json.tpl +11 -0
package/template/ai/contracts/api-boundary.md.tpl +17 -0
package/template/ai/contracts/app-legibility.contract.json.tpl +11 -0
package/template/ai/contracts/app-legibility.md.tpl +24 -0
package/template/ai/contracts/codex-hooks.contract.json.tpl +15 -0
package/template/ai/contracts/codex-hooks.md.tpl +18 -0
package/template/ai/contracts/github-safety.contract.json.tpl +11 -0
package/template/ai/contracts/github-safety.md.tpl +15 -0
package/template/ai/contracts/release-flow.contract.json.tpl +12 -0
package/template/ai/contracts/release-flow.md.tpl +15 -0
package/template/ai/contracts/repo-boundaries.contract.json.tpl +12 -0
package/template/ai/contracts/repo-boundaries.md.tpl +18 -0
package/template/ai/contracts/security-boundary.contract.json.tpl +11 -0
package/template/ai/contracts/security-boundary.md.tpl +19 -0
package/template/ai/knowledge-manifest.json.tpl +149 -0
package/template/ai/model-overlays/anthropic/CLAUDE.md.tpl +14 -0
package/template/ai/model-overlays/openai/AGENTS.md.tpl +13 -0
package/template/ai/plans/README.md.tpl +10 -0
package/template/ai/plans/tech-debt.md.tpl +7 -0
package/template/ai/skills/README.md.tpl +15 -0
package/template/ai/skills/review-architecture.md.tpl +41 -0
package/template/ai/skills/review-contract-drift.md.tpl +41 -0
package/template/ai/skills/review-governance-drift.md.tpl +42 -0
package/template/ai/skills/review-security.md.tpl +40 -0
package/template/ai/specs/README.md.tpl +14 -0
package/template/ai/templates/README.md.tpl +13 -0
package/template/ai/templates/fixtures/issues/invalid-placeholder.md.tpl +20 -0
package/template/ai/templates/fixtures/issues/invalid-protected-surface.md.tpl +21 -0
package/template/ai/templates/fixtures/issues/valid-ready.md.tpl +105 -0
package/template/ai/templates/issue-template.md.tpl +107 -0
package/template/ai/templates/task-brief-template.md.tpl +185 -0
package/template/ai/workspace/LOCAL-STACK.md.tpl +21 -0
package/template/ai/workspace/REPOS.md.tpl +19 -0
package/template/ai/workspace/SESSION-BOOTSTRAP.md.tpl +27 -0
package/template/ai/workspace/SYSTEM-MAP.md.tpl +19 -0
package/template/ai/workspace/TEST-STRATEGY.md.tpl +22 -0
package/template/consumer/.claude/CLAUDE.md.tpl +14 -0
package/template/consumer/AGENTS.md.tpl +23 -0
package/template/consumer/CLAUDE.md.tpl +15 -0
package/template/scripts/bootstrap-codex-worktree.mjs.tpl +52 -0
package/template/scripts/bootstrap-workspace.mjs.tpl +100 -0
package/template/scripts/check-claude-compatibility.mjs.tpl +120 -0
package/template/scripts/check-codex-hooks.mjs.tpl +190 -0
package/template/scripts/check-contract-manifests.mjs.tpl +81 -0
package/template/scripts/check-garbage-collection.mjs.tpl +25 -0
package/template/scripts/check-html-views.mjs.tpl +60 -0
package/template/scripts/check-issue-template.mjs.tpl +167 -0
package/template/scripts/check-knowledge-manifest.mjs.tpl +82 -0
package/template/scripts/check-overlay-drift.mjs.tpl +49 -0
package/template/scripts/check-plans.mjs.tpl +70 -0
package/template/scripts/check-readiness.mjs.tpl +130 -0
package/template/scripts/check-review-skills.mjs.tpl +48 -0
package/template/scripts/check-task-template.mjs.tpl +63 -0
package/template/scripts/check-template-governance.mjs.tpl +161 -0
package/template/scripts/check-workspace.mjs.tpl +212 -0
package/template/scripts/check-worktree-bootstrap-fixtures.mjs.tpl +122 -0
package/template/scripts/check-worktrees.mjs.tpl +69 -0
package/template/scripts/fixtures/worktrees/README.md.tpl +4 -0
package/template/scripts/generate-html-views.mjs.tpl +189 -0
package/template/scripts/hooks/codex-hook.mjs.tpl +21 -0
package/template/scripts/hooks/lib/codex-hooks-core.mjs.tpl +114 -0
package/template/scripts/lib/worktree-bootstrap.mjs.tpl +388 -0
package/template/scripts/validate-governance.mjs.tpl +78 -0
package/template/workspace/.claude/CLAUDE.md.tpl +9 -0
package/template/workspace/.claude/rules/harness-client-surfaces.md.tpl +15 -0
package/template/workspace/.claude/settings.json.tpl +10 -0
package/template/workspace/AGENTS.md.tpl +17 -0
package/template/workspace/CLAUDE.md.tpl +18 -0

package/template/scripts/generate-html-views.mjs.tpl ADDED Viewed

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+const outputArgIndex = args.indexOf("--output");
+const outputRoot = outputArgIndex === -1 ? repoRoot : path.resolve(args[outputArgIndex + 1]);
+const viewsDir = path.join(outputRoot, "ai/views");
+async function read(relativePath) {
+  try {
+    return await readFile(path.join(repoRoot, relativePath), "utf8");
+  } catch {
+    return "";
+  }
+}
+async function files(relativeDir, suffix) {
+  try {
+    const entries = await readdir(path.join(repoRoot, relativeDir), { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(suffix))
+      .map((entry) => `${relativeDir}/${entry.name}`)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+function titleFromMarkdown(content, fallback) {
+  return content.match(/^#\s+(.+)$/m)?.[1] ?? fallback;
+}
+function frontMatterValue(content, key) {
+  return content.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim() ?? "";
+}
+function layout(title, body) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)} - {{PROJECT_NAME}} Harness Views</title>
+  <style>
+    body { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 0; color: #172026; background: #f7f8fa; }
+    header, main { max-width: 1080px; margin: 0 auto; padding: 24px; }
+    header { border-bottom: 1px solid #d8dee4; background: #fff; }
+    h1 { margin: 0 0 8px; font-size: 28px; }
+    h2 { margin-top: 28px; font-size: 18px; }
+    p { line-height: 1.5; }
+    a { color: #0969da; }
+    table { width: 100%; border-collapse: collapse; background: #fff; border: 1px solid #d8dee4; }
+    th, td { padding: 10px 12px; border-bottom: 1px solid #d8dee4; text-align: left; vertical-align: top; }
+    th { background: #eef2f6; font-size: 13px; }
+    code { background: #eef2f6; padding: 2px 4px; border-radius: 4px; }
+    .note { color: #57606a; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>${escapeHtml(title)}</h1>
+    <p class="note">Generated review artifact. Markdown, JSON, and YAML files remain canonical.</p>
+  </header>
+  <main>
+${body}
+  </main>
+</body>
+</html>
+`;
+}
+function table(headers, rows) {
+  const head = headers.map((header) => `<th>${escapeHtml(header)}</th>`).join("");
+  const body = rows.map((row) => `<tr>${row.map((cell) => `<td>${cell}</td>`).join("")}</tr>`).join("\n");
+  return `<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`;
+}
+async function indexView() {
+  return layout("Harness Review Views", `
+    <h2>Views</h2>
+    <ul>
+      <li><a href="plans.html">Plans</a></li>
+      <li><a href="contracts.html">Contracts</a></li>
+      <li><a href="readiness.html">Readiness</a></li>
+      <li><a href="quality.html">Quality</a></li>
+      <li><a href="workspace.html">Workspace</a></li>
+    </ul>
+    <h2>Canonical Sources</h2>
+    <p>Start from <code>ai/HUB.md</code>, <code>ai/context.md</code>, and <code>ai/knowledge-manifest.json</code>.</p>
+`);
+}
+async function plansView() {
+  const planFiles = await files("ai/plans/active", ".md");
+  const rows = [];
+  for (const file of planFiles) {
+    const content = await read(file);
+    rows.push([
+      `<code>${escapeHtml(file)}</code>`,
+      escapeHtml(titleFromMarkdown(content, path.basename(file))),
+      escapeHtml(frontMatterValue(content, "status") || "n/a"),
+      escapeHtml(frontMatterValue(content, "risk") || "n/a"),
+      escapeHtml(frontMatterValue(content, "autonomy") || "n/a"),
+    ]);
+  }
+  return layout("Plans", table(["Source", "Title", "Status", "Risk", "Autonomy"], rows));
+}
+async function contractsView() {
+  const contractFiles = await files("ai/contracts", ".md");
+  const rows = [];
+  for (const file of contractFiles.filter((item) => item !== "ai/contracts/README.md")) {
+    const content = await read(file);
+    rows.push([
+      `<code>${escapeHtml(file)}</code>`,
+      escapeHtml(titleFromMarkdown(content, path.basename(file))),
+      `<code>${escapeHtml(file.replace(/\\.md$/, ".contract.json"))}</code>`,
+    ]);
+  }
+  return layout("Contracts", table(["Source", "Title", "Manifest"], rows));
+}
+async function qualityView() {
+  const quality = await read("ai/QUALITY.md");
+  const lines = quality.split(/\r?\n/).filter((line) => /^[-*]\s+/.test(line)).slice(0, 20);
+  return layout("Quality", `
+    <p>Source: <code>ai/QUALITY.md</code></p>
+    <ul>${lines.map((line) => `<li>${escapeHtml(line.replace(/^[-*]\s+/, ""))}</li>`).join("")}</ul>
+`);
+}
+async function readinessView() {
+  const readiness = await read("ai/READINESS.md");
+  const rows = [];
+  const lines = readiness.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith("| Gate | Command | Required evidence |"));
+  if (start !== -1) {
+    for (const line of lines.slice(start + 2)) {
+      if (!line.startsWith("|")) break;
+      const cells = line
+        .split("|")
+        .slice(1, -1)
+        .map((cell) => escapeHtml(cell.trim().replaceAll("`", "")));
+      if (cells.length === 3) rows.push(cells);
+    }
+  }
+  return layout("Readiness", `
+    <p>Source: <code>ai/READINESS.md</code></p>
+    ${table(["Gate", "Command", "Required evidence"], rows)}
+`);
+}
+async function workspaceView() {
+  const workspaceFiles = await files("ai/workspace", ".md");
+  const rows = [];
+  for (const file of workspaceFiles) {
+    const content = await read(file);
+    rows.push([`<code>${escapeHtml(file)}</code>`, escapeHtml(titleFromMarkdown(content, path.basename(file)))]);
+  }
+  return layout("Workspace", table(["Source", "Title"], rows));
+}
+const outputs = {
+  "index.html": await indexView(),
+  "plans.html": await plansView(),
+  "contracts.html": await contractsView(),
+  "readiness.html": await readinessView(),
+  "quality.html": await qualityView(),
+  "workspace.html": await workspaceView(),
+};
+await mkdir(viewsDir, { recursive: true });
+for (const [name, content] of Object.entries(outputs)) {
+  await writeFile(path.join(viewsDir, name), content);
+}
+console.log(`Generated ${Object.keys(outputs).length} HTML view(s).`);

package/template/scripts/hooks/codex-hook.mjs.tpl ADDED Viewed

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { allow, context, evaluate, parseInput } from "./lib/codex-hooks-core.mjs";
+const event = process.argv[2] ?? "UnknownEvent";
+function emit(result) {
+  const output = JSON.stringify(result);
+  console.log(output);
+  if (result.action === "deny") process.exit(2);
+}
+try {
+  const rawInput = readFileSync(0, "utf8");
+  emit(evaluate(event, parseInput(rawInput)));
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const result = context(`Codex hook could not parse input safely: ${message}`);
+  emit(result);
+}

package/template/scripts/hooks/lib/codex-hooks-core.mjs.tpl ADDED Viewed

@@ -0,0 +1,114 @@
+const docsWorkflow = "ai/WORKFLOW.md";
+const docsQuality = "ai/QUALITY.md";
+const docsHub = "ai/HUB.md";
+const docsContext = "ai/context.md";
+const taskBriefTemplate = "ai/templates/task-brief-template.md";
+const eventSessionStart = "SessionStart";
+const eventUserPromptSubmit = "UserPromptSubmit";
+const eventPreToolUse = "PreToolUse";
+const eventPermissionRequest = "PermissionRequest";
+const eventPostToolUse = "PostToolUse";
+const eventStop = "Stop";
+const workflowDocs = [docsWorkflow, docsHub, docsContext];
+const taskDocs = [docsWorkflow, taskBriefTemplate];
+const postToolDocs = [docsWorkflow, docsQuality];
+const stopDocs = [docsWorkflow, docsQuality];
+const promptRequiresContextPattern = /\b(implement|fix|change|refactor|update|edit)\b/i;
+const commandFailurePattern = /fail|timeout|error/i;
+const finalMessagePattern = /commands run|validation|files changed/i;
+const allowedActionAllow = "allow";
+export const denyRules = [
+  {
+    id: "destructive-git-reset",
+    pattern: /\bgit\s+reset\s+--hard\b/i,
+    prevents: "discarding local work without explicit human approval",
+    remediation: "stop and ask for approval before destructive git operations",
+    policyDocs: ["ai/WORKFLOW.md", "ai/RUNNER-SAFETY.md"],
+    falsePositiveNote: "Only applies to destructive reset operations.",
+  },
+  {
+    id: "force-push",
+    pattern: /\bgit\s+push\b.*\s--force(?:-with-lease)?\b/i,
+    prevents: "rewriting remote history without explicit human approval",
+    remediation: "use a normal push or ask for approval with the exact branch and reason",
+    policyDocs: ["ai/WORKFLOW.md", "ai/RUNNER-SAFETY.md"],
+    falsePositiveNote: "Normal non-force pushes are not denied by this rule.",
+  },
+  {
+    id: "secret-read",
+    pattern: /\b(?:cat|sed|grep|rg|less|tail|head)\b.*(?:\.env|secret|token|credential)/i,
+    prevents: "unnecessary secret exposure in agent context",
+    remediation: "read documented env var names instead of secret values",
+    policyDocs: ["ai/RUNNER-SAFETY.md", "ai/contracts/security-boundary.md"],
+    falsePositiveNote: "Adjust this generic rule if the project has fixture files with safe secret-like names.",
+  },
+];
+export function parseInput(rawInput) {
+  if (!rawInput.trim()) return {};
+  return JSON.parse(rawInput);
+}
+export function context(message, docs = []) {
+  return { action: "context", message, docs };
+}
+export function allow(message = "Allowed by harness hook policy.") {
+  return { action: "allow", message };
+}
+export function deny(rule) {
+  return {
+    action: "deny",
+    message: `${rule.id}: ${rule.prevents}. ${rule.remediation}.`,
+    docs: rule.policyDocs,
+  };
+}
+export function evaluate(event, input) {
+  if (event === "SessionStart") {
+    return context("Load the repo entrypoint, ai/AGENTS.md, ai/HUB.md, and ai/context.md before feature work.", [
+      "AGENTS.md",
+      ...workflowDocs,
+    ]);
+  }
+  if (event === eventUserPromptSubmit) {
+    const prompt = String(input.prompt ?? "");
+    if (promptRequiresContextPattern.test(prompt)) {
+      return context("Before editing, identify expected files, preserved contracts, and validation commands.", [
+        ...taskDocs,
+      ]);
+    }
+    return allow();
+  }
+  if (event === eventPreToolUse || event === eventPermissionRequest) {
+    const command = String(input.command ?? input.toolInput?.cmd ?? "");
+    for (const rule of denyRules) {
+      if (rule.pattern.test(command)) return deny(rule);
+    }
+    return allow();
+  }
+  if (event === eventPostToolUse) {
+    const exitCode = Number(input.exitCode ?? 0);
+    const status = String(input.status ?? "");
+    if (exitCode !== 0 || commandFailurePattern.test(status)) {
+      return context("A command failed or timed out. Report the exact command, failure, and next repair step.", [...postToolDocs]);
+    }
+    return allow();
+  }
+  if (event === eventStop) {
+    const changedFiles = Array.isArray(input.changedFiles) ? input.changedFiles : [];
+    const finalMessage = String(input.finalMessage ?? "");
+    if (changedFiles.length > 0 && !finalMessagePattern.test(finalMessage)) {
+      return context("Final response should include files changed and validation evidence.", [...stopDocs]);
+    }
+    return allow();
+  }
+  return context("Unknown hook event. Defaulting to context-only behavior.");
+}