@structor-dev/cli 0.1.0

package/template/scripts/bootstrap-workspace.mjs.tpl

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const workspaceRoot = path.resolve(repoRoot, "..");
+const consumers = {{CONSUMER_CONFIG_JSON}};
+const models = {
+  openai: {{MODEL_OPENAI_ENABLED}},
+  anthropic: {{MODEL_ANTHROPIC_ENABLED}},
+};
+const clientSupport = {
+  claudeRules: {{CLIENT_CLAUDE_RULES_ENABLED}},
+};
+
+function parseArgs(argv) {
+  return {
+    force: argv.includes("--force"),
+    dryRun: argv.includes("--dry-run"),
+  };
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyIfAllowed(sourceRelative, targetRelative, options) {
+  const source = path.join(repoRoot, sourceRelative);
+  const target = path.join(workspaceRoot, targetRelative);
+  if (!(await exists(source))) return;
+  if (options.dryRun) {
+    console.log(`would install ${target}`);
+    return;
+  }
+  if ((await exists(target)) && !options.force) {
+    console.log(`skipped existing ${target}`);
+    return;
+  }
+  await mkdir(path.dirname(target), { recursive: true });
+  await cp(source, target);
+  console.log(`installed ${target}`);
+}
+
+async function verifyConsumers() {
+  const missing = [];
+  for (const consumer of consumers) {
+    const consumerRoot = path.resolve(workspaceRoot, consumer.workspacePath);
+    if (!(await exists(consumerRoot))) {
+      missing.push(`${consumer.name}: expected repo at ${consumerRoot}`);
+    }
+  }
+  if (missing.length > 0) {
+    throw new Error(`Missing consumer repos:\n${missing.map((item) => `- ${item}`).join("\n")}`);
+  }
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  await verifyConsumers();
+
+  if (models.openai) {
+    await copyIfAllowed("workspace/AGENTS.md", "AGENTS.md", options);
+  }
+  if (models.anthropic) {
+    await copyIfAllowed("workspace/CLAUDE.md", "CLAUDE.md", options);
+    await copyIfAllowed("workspace/.claude/CLAUDE.md", ".claude/CLAUDE.md", options);
+    await copyIfAllowed("workspace/.claude/settings.json", ".claude/settings.json", options);
+    if (clientSupport.claudeRules) {
+      await copyIfAllowed(
+        "workspace/.claude/rules/harness-client-surfaces.md",
+        ".claude/rules/harness-client-surfaces.md",
+        options,
+      );
+    }
+  }
+
+  if (!options.dryRun) {
+    execFileSync(process.execPath, [path.join(repoRoot, "scripts/check-workspace.mjs")], {
+      cwd: repoRoot,
+      stdio: "inherit",
+    });
+  }
+
+  console.log("Workspace bootstrap complete.");
+  console.log(`Workspace root: ${workspaceRoot}`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/template/scripts/check-claude-compatibility.mjs.tpl

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import { readFile, readdir, access } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const claudeRulesEnabled = {{CLIENT_CLAUDE_RULES_ENABLED}};
+const claudeHooksEnabled = {{CLIENT_CLAUDE_HOOKS_ENABLED}};
+const claudeSkillsEnabled = {{CLIENT_CLAUDE_SKILLS_ENABLED}};
+
+const requiredFiles = [
+  "CLAUDE.md",
+  ".claude/CLAUDE.md",
+  ".claude/settings.json",
+  "ai/model-overlays/anthropic/CLAUDE.md",
+];
+
+if (claudeRulesEnabled) requiredFiles.push(".claude/rules/harness-client-surfaces.md");
+
+async function exists(relativePath) {
+  try {
+    await access(path.join(repoRoot, relativePath), fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function read(relativePath) {
+  return readFile(path.join(repoRoot, relativePath), "utf8");
+}
+
+async function readJson(relativePath) {
+  return JSON.parse(await read(relativePath));
+}
+
+async function listMarkdownFiles(relativeRoot) {
+  const absoluteRoot = path.join(repoRoot, relativeRoot);
+  const files = [];
+  async function walk(currentPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolute = path.join(currentPath, entry.name);
+      const relative = path.relative(repoRoot, absolute).replaceAll(path.sep, "/");
+      if (entry.isDirectory()) await walk(absolute);
+      else if (entry.isFile() && entry.name.endsWith(".md")) files.push(relative);
+    }
+  }
+  if (await exists(relativeRoot)) await walk(absoluteRoot);
+  return files;
+}
+
+function requireIncludes(content, needle, label, errors) {
+  if (!content.includes(needle)) errors.push(`${label} must include '${needle}'.`);
+}
+
+const errors = [];
+for (const relativePath of requiredFiles) {
+  if (!(await exists(relativePath))) errors.push(`${relativePath} is required for Claude Code compatibility.`);
+}
+
+if (errors.length === 0) {
+  const rootClaude = await read("CLAUDE.md");
+  requireIncludes(rootClaude, "Claude Code", "CLAUDE.md", errors);
+  requireIncludes(rootClaude, "./ai/AGENTS.md", "CLAUDE.md", errors);
+  requireIncludes(rootClaude, "./ai/HUB.md", "CLAUDE.md", errors);
+  if (/^\s*1\.\s+`\.\/AGENTS\.md`/m.test(rootClaude)) {
+    errors.push("CLAUDE.md must not require Claude Code to start from AGENTS.md.");
+  }
+
+  const claudeProject = await read(".claude/CLAUDE.md");
+  requireIncludes(claudeProject, "root `CLAUDE.md`", ".claude/CLAUDE.md", errors);
+
+  const settings = await readJson(".claude/settings.json");
+  if (!settings.permissions || !Array.isArray(settings.permissions.deny)) {
+    errors.push(".claude/settings.json must define permissions.deny.");
+  }
+  for (const denyPattern of ["Read(./.agent.env)", "Read(./.env)", "Read(./.env.*)"]) {
+    if (!settings.permissions?.deny?.includes(denyPattern)) {
+      errors.push(`.claude/settings.json permissions.deny must include ${denyPattern}.`);
+    }
+  }
+  if (!claudeHooksEnabled && Object.hasOwn(settings, "hooks")) {
+    errors.push(".claude/settings.json must not configure Claude hooks unless clientSupport.claude.hooks is enabled.");
+  }
+
+  if (claudeRulesEnabled) {
+    const rule = await read(".claude/rules/harness-client-surfaces.md");
+    for (const token of ["paths:", "AGENTS.md", "CLAUDE.md", ".claude/**", "ai/model-overlays/**"]) {
+      requireIncludes(rule, token, ".claude/rules/harness-client-surfaces.md", errors);
+    }
+  }
+
+  if (claudeSkillsEnabled) {
+    const skillFiles = await listMarkdownFiles(".claude/skills");
+    const skillRoots = new Set(skillFiles.map((file) => file.match(/^\.claude\/skills\/([^/]+)\//)?.[1]).filter(Boolean));
+    for (const skillName of skillRoots) {
+      if (!skillFiles.includes(`.claude/skills/${skillName}/SKILL.md`)) {
+        errors.push(`.claude/skills/${skillName}/SKILL.md is required for committed Claude skill directories.`);
+      }
+    }
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Claude compatibility check failed.");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log("Claude compatibility check passed.");
+console.log("Supported Claude Code surface:");
+console.log("- CLAUDE.md");
+console.log("- .claude/CLAUDE.md");
+console.log("- .claude/settings.json");
+if (claudeRulesEnabled) console.log("- .claude/rules/harness-client-surfaces.md");
+if (!claudeHooksEnabled) console.log("Deferred Claude Code surface: .claude/hooks/**");
+if (!claudeSkillsEnabled) console.log("Deferred Claude Code surface: .claude/skills/**");

package/template/scripts/check-codex-hooks.mjs.tpl

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import { readFile, readdir } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { denyRules } from "./hooks/lib/codex-hooks-core.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const eventSessionStart = "SessionStart";
+const eventUserPromptSubmit = "UserPromptSubmit";
+const eventPreToolUse = "PreToolUse";
+const eventPermissionRequest = "PermissionRequest";
+const eventPostToolUse = "PostToolUse";
+const eventStop = "Stop";
+const hookCommandForEvent = (event) => `node scripts/hooks/codex-hook.mjs ${event} --json`;
+const fixtureTimeoutMs = 2000;
+const defaultExitCodeSuccess = 0;
+
+const expectedEvents = [
+  eventSessionStart,
+  eventUserPromptSubmit,
+  eventPreToolUse,
+  eventPermissionRequest,
+  eventPostToolUse,
+  eventStop,
+];
+
+const fixtures = [
+  {
+    name: "session-start-context",
+    event: eventSessionStart,
+    input: { cwd: repoRoot },
+    expectedAction: "context",
+    expectedExitCode: defaultExitCodeSuccess,
+  },
+  {
+    name: "prompt-implementation-context",
+    event: eventUserPromptSubmit,
+    input: { prompt: "implement the next task" },
+    expectedAction: "context",
+    expectedExitCode: defaultExitCodeSuccess,
+  },
+  {
+    name: "destructive-command-deny",
+    event: eventPreToolUse,
+    input: { toolInput: { cmd: "git reset --hard HEAD" } },
+    expectedAction: "deny",
+    expectedExitCode: 2,
+  },
+  {
+    name: "failed-validation-context",
+    event: eventPostToolUse,
+    input: { command: "node scripts/validate-governance.mjs", exitCode: 1 },
+    expectedAction: "context",
+    expectedExitCode: defaultExitCodeSuccess,
+  },
+  {
+    name: "stop-no-change-allow",
+    event: eventStop,
+    input: { changedFiles: [] },
+    expectedAction: "allow",
+    expectedExitCode: defaultExitCodeSuccess,
+  },
+  {
+    name: "malformed-input-context",
+    event: eventPreToolUse,
+    rawInput: "{not json",
+    expectedAction: "context",
+    expectedExitCode: defaultExitCodeSuccess,
+  },
+];
+
+async function readJson(relativePath) {
+  return JSON.parse(await readFile(path.join(repoRoot, relativePath), "utf8"));
+}
+
+function checkTimeoutLimit(errors, event, timeoutMs) {
+  if (timeoutMs && timeoutMs > fixtureTimeoutMs) {
+    errors.push(`${event} timeoutMs must be ${fixtureTimeoutMs} or less.`);
+  }
+}
+
+function hookCommandFor(event) {
+  return hookCommandForEvent(event);
+}
+
+async function checkConfig(errors) {
+  const config = await readJson(".codex/hooks.json");
+  if (config.version !== 1) errors.push(".codex/hooks.json must set version: 1.");
+  for (const event of expectedEvents) {
+    const entries = config.hooks?.[event];
+    if (!Array.isArray(entries) || entries.length === 0) {
+      errors.push(`.codex/hooks.json missing ${event} hook entry.`);
+      continue;
+    }
+    const commands = entries.flatMap((entry) => (entry.hooks ?? []).map((hook) => hook.command));
+    const expectedCommand = hookCommandFor(event);
+    if (!commands.includes(expectedCommand)) {
+      errors.push(`${event} must reference committed command '${expectedCommand}'.`);
+    }
+    for (const entry of entries) {
+      checkTimeoutLimit(errors, event, entry.timeoutMs);
+    }
+  }
+}
+
+async function checkHookScripts(errors) {
+  const hooksDir = path.join(repoRoot, "scripts/hooks");
+  const files = (await readdir(hooksDir, { recursive: true }))
+    .filter((file) => file.endsWith(".mjs"))
+    .map((file) => `scripts/hooks/${file}`);
+  const bannedPatterns = [
+    { pattern: /node:child_process|from\s+["']child_process["']/i, label: "process supervision" },
+    { pattern: /\b(fetch|XMLHttpRequest)\s*\(/, label: "network call" },
+    { pattern: /from\s+["']node:fs\/promises["']|from\s+["']fs\/promises["']/i, label: "file-system write-capable import" },
+    { pattern: /\b(writeFile|appendFile|mkdir|rm|unlink|rmdir)\s*\(/, label: "file mutation" },
+  ];
+  for (const relativePath of files) {
+    const source = await readFile(path.join(repoRoot, relativePath), "utf8");
+    for (const banned of bannedPatterns) {
+      if (banned.pattern.test(source)) {
+        errors.push(`${relativePath} contains ${banned.label} token. Hook scripts must stay deterministic and local.`);
+      }
+    }
+  }
+}
+
+function checkDenyRules(errors) {
+  for (const rule of denyRules) {
+    for (const field of ["id", "prevents", "remediation", "falsePositiveNote"]) {
+      if (!rule[field]) errors.push(`deny rule missing ${field}.`);
+    }
+    if (!Array.isArray(rule.policyDocs) || rule.policyDocs.length === 0) {
+      errors.push(`${rule.id ?? "deny rule"} missing policyDocs.`);
+    }
+    if (!(rule.pattern instanceof RegExp)) {
+      errors.push(`${rule.id ?? "deny rule"} missing RegExp pattern.`);
+    }
+  }
+}
+
+function runFixture(fixture) {
+  const child = spawnSync(process.execPath, ["scripts/hooks/codex-hook.mjs", fixture.event, "--json"], {
+    cwd: repoRoot,
+    input: fixture.rawInput ?? JSON.stringify(fixture.input ?? {}),
+    encoding: "utf8",
+    timeout: fixtureTimeoutMs,
+  });
+  return child;
+}
+
+function checkFixtures(errors) {
+  for (const fixture of fixtures) {
+    const child = runFixture(fixture);
+    if (child.error) {
+      errors.push(`${fixture.name}: hook execution failed (${child.error.message}).`);
+      continue;
+    }
+    let output;
+    try {
+      output = JSON.parse(child.stdout);
+    } catch {
+      errors.push(`${fixture.name}: hook did not return JSON output. stdout=${JSON.stringify(child.stdout)}`);
+      continue;
+    }
+    if (child.status !== fixture.expectedExitCode) {
+      errors.push(`${fixture.name}: expected exit ${fixture.expectedExitCode}, got ${child.status}.`);
+    }
+    if (output.action !== fixture.expectedAction) {
+      errors.push(`${fixture.name}: expected action ${fixture.expectedAction}, got ${output.action}.`);
+    }
+  }
+}
+
+const errors = [];
+await checkConfig(errors);
+await checkHookScripts(errors);
+checkDenyRules(errors);
+checkFixtures(errors);
+
+if (errors.length > 0) {
+  console.error("Codex hook check failed.");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log("Codex hook check passed.");
+console.log("External writes/network/runtime-state writes: none detected in hook scripts.");

package/template/scripts/check-contract-manifests.mjs.tpl

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { access, readFile, readdir } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const contractsDirectory = "ai/contracts";
+const contractsReadmePath = `${contractsDirectory}/README.md`;
+const contractFileSuffix = ".contract.json";
+const docFileSuffix = ".md";
+const requiredFields = ["id", "name", "version", "owners", "affectedRepos", "requiredFiles"];
+const semverPattern = /^\d+\.\d+\.\d+$/;
+
+async function exists(relativePath) {
+  try {
+    await access(path.join(repoRoot, relativePath), fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateManifest(manifest, label, errors) {
+  if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) {
+    errors.push(`${label} must be a JSON object.`);
+    return;
+  }
+  for (const field of requiredFields) {
+    if (!Object.hasOwn(manifest, field)) {
+      errors.push(`${label} is missing '${field}'.`);
+    }
+  }
+  if (typeof manifest.version === "string" && !semverPattern.test(manifest.version)) {
+    errors.push(`${label}.version must use semver-like x.y.z.`);
+  }
+  for (const field of ["owners", "affectedRepos", "requiredFiles"]) {
+    if (!Array.isArray(manifest[field]) || manifest[field].length === 0) {
+      errors.push(`${label}.${field} must be a non-empty array.`);
+    }
+  }
+}
+
+const errors = [];
+const entries = await readdir(path.join(repoRoot, contractsDirectory), { withFileTypes: true });
+const readme = await readFile(path.join(repoRoot, contractsReadmePath), "utf8");
+
+for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith(docFileSuffix) && item.name !== "README.md")) {
+  if (!readme.includes(entry.name)) {
+    errors.push(`${contractsDirectory}/${entry.name} is not linked from ${contractsReadmePath}.`);
+  }
+}
+
+for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith(contractFileSuffix))) {
+  const relativePath = `${contractsDirectory}/${entry.name}`;
+  try {
+    const manifest = JSON.parse(await readFile(path.join(repoRoot, relativePath), "utf8"));
+    validateManifest(manifest, relativePath, errors);
+    for (const requiredFile of manifest.requiredFiles ?? []) {
+      if (!(await exists(requiredFile))) {
+        errors.push(`${relativePath} requires missing file ${requiredFile}.`);
+      }
+    }
+  } catch {
+    errors.push(`${relativePath} must be valid JSON.`);
+  }
+
+  const docPath = `${relativePath.replace(contractFileSuffix, docFileSuffix)}`;
+  if (!(await exists(docPath))) {
+    errors.push(`${relativePath} must have a sibling ${docPath}.`);
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Contract manifest check failed.");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log("Contract manifest check passed.");

package/template/scripts/check-garbage-collection.mjs.tpl

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { readFile } 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 garbageCollectionPolicyPath = "ai/AGENT-GARBAGE-COLLECTION.md";
+const requiredGarbagePhrases = ["archive", "stale", "generated", "validation"];
+const content = await readFile(path.join(repoRoot, garbageCollectionPolicyPath), "utf8");
+const errors = [];
+
+for (const phrase of requiredGarbagePhrases) {
+  if (!content.toLowerCase().includes(phrase)) {
+    errors.push(`${garbageCollectionPolicyPath} should mention ${phrase}.`);
+  }
+}
+
+if (errors.length > 0) {
+  console.error("Garbage collection check failed.");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log("Garbage collection check passed.");

package/template/scripts/check-html-views.mjs.tpl

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import { mkdtemp, readFile, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const tempDirectoryTemplate = "{{PROJECT_SLUG}}-views-";
+const viewsDirectory = "ai/views";
+const generateHtmlViewsScript = "scripts/generate-html-views.mjs";
+const staleGeneratedViewInstruction = `run node ${generateHtmlViewsScript}`;
+const htmlExtension = ".html";
+const expectedViewPathPrefix = `${viewsDirectory}/`;
+const tempRoot = await mkdtemp(path.join(os.tmpdir(), tempDirectoryTemplate));
+
+execFileSync(process.execPath, [generateHtmlViewsScript, "--output", tempRoot], {
+  cwd: repoRoot,
+  stdio: "pipe",
+});
+
+async function htmlFiles(baseDir) {
+  const dir = path.join(baseDir, viewsDirectory);
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(htmlExtension)).map((entry) => entry.name).sort();
+}
+
+const expected = await htmlFiles(tempRoot);
+const actual = await htmlFiles(repoRoot);
+const errors = [];
+
+for (const name of expected) {
+  const expectedViewPath = `${expectedViewPathPrefix}${name}`;
+  if (!actual.includes(name)) {
+    errors.push(`missing generated view ${expectedViewPath}`);
+    continue;
+  }
+  const expectedContent = await readFile(path.join(tempRoot, viewsDirectory, name), "utf8");
+  const actualContent = await readFile(path.join(repoRoot, viewsDirectory, name), "utf8");
+  if (expectedContent !== actualContent) {
+    errors.push(`stale generated view ${expectedViewPath}; ${staleGeneratedViewInstruction}`);
+  }
+}
+
+for (const name of actual) {
+  if (!expected.includes(name)) {
+    errors.push(`unexpected generated view ${expectedViewPathPrefix}${name}`);
+  }
+}
+
+if (errors.length > 0) {
+  console.error("HTML view check failed.");
+  for (const error of errors) console.error(`- ${error}`);
+  process.exit(1);
+}
+
+console.log("HTML view check passed.");