@structor-dev/cli 0.1.0

package/docs/issues/0001-structor-doctor.md

@@ -0,0 +1,39 @@
+# Add a Structor doctor command
+
+## Summary
+
+Add a future `structor doctor` command that diagnoses and optionally repairs a
+previously generated Structor workspace after installation drift, stale consumer
+entrypoints, moved folders, or incomplete setup.
+
+## Motivation
+
+The setup wizard should make first-time installation easy, but users may later
+move folders, edit pointer files, delete generated files, or partially complete
+manual setup. A doctor flow would make Structor easier to adopt by providing a
+clear recovery path instead of forcing users to understand every generated file.
+
+## Scope
+
+- Inspect `harness.config.json`, generated harness files, workspace pointers,
+  and configured consumer entrypoints.
+- Report healthy, missing, stale, and unsafe surfaces.
+- Offer preview-first repairs for local files that Structor owns.
+- Reuse existing validation commands where possible.
+- Avoid runner behavior, polling, remote services, or automatic repository
+  mutation without confirmation.
+
+## Non-Goals
+
+- No external service repair.
+- No GitHub, CI, deployment, database, or production mutations.
+- No automatic rewrite of hand-written consumer instructions without explicit
+  confirmation.
+- No replacement for the setup wizard or deterministic initializer.
+
+## Open Questions
+
+- Should repair be a separate `structor doctor --repair` mode or an interactive
+  prompt after diagnosis?
+- Which files should be considered Structor-owned versus user-owned?
+- Should doctor be available in the wizard MVP or shipped as a follow-up issue?

package/examples/frontend-backend/harness.config.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "../../schemas/harness-config.schema.json",
+  "project": {
+    "name": "Frontend Backend Product",
+    "slug": "frontend-backend-product",
+    "harnessRepoName": "frontend-backend-product-structor"
+  },
+  "output": {
+    "path": "../../generated/frontend-backend-product-structor"
+  },
+  "models": {
+    "openai": true,
+    "anthropic": true
+  },
+  "consumers": [
+    {
+      "name": "product-frontend",
+      "path": "../../../product-frontend",
+      "purpose": "Frontend application repository",
+      "validation": {
+        "lint": "npm run lint",
+        "build": "npm run build"
+      }
+    },
+    {
+      "name": "product-backend",
+      "path": "../../../product-backend",
+      "purpose": "Backend API repository",
+      "validation": {
+        "lint": "npm run lint",
+        "test": "npm test"
+      }
+    }
+  ]
+}

package/examples/openai-and-anthropic/harness.config.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../schemas/harness-config.schema.json",
+  "project": {
+    "name": "Multi Model Product",
+    "slug": "multi-model-product",
+    "harnessRepoName": "multi-model-product-structor"
+  },
+  "output": {
+    "path": "../../generated/multi-model-product-structor"
+  },
+  "models": {
+    "openai": true,
+    "anthropic": true
+  },
+  "consumers": [
+    {
+      "name": "multi-model-app",
+      "path": "../../../multi-model-app",
+      "purpose": "Application repository used by both OpenAI and Anthropic agents",
+      "validation": {
+        "install": "npm install",
+        "lint": "npm run lint",
+        "test": "npm test",
+        "build": "npm run build"
+      }
+    }
+  ]
+}

package/examples/single-repo/harness.config.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../schemas/harness-config.schema.json",
+  "project": {
+    "name": "Single Repo Product",
+    "slug": "single-repo-product",
+    "harnessRepoName": "single-repo-product-structor"
+  },
+  "output": {
+    "path": "../../generated/single-repo-product-structor"
+  },
+  "models": {
+    "openai": true,
+    "anthropic": false
+  },
+  "consumers": [
+    {
+      "name": "single-repo-app",
+      "path": "../../../single-repo-app",
+      "purpose": "Application repository",
+      "validation": {
+        "lint": "npm run lint",
+        "test": "npm test"
+      }
+    }
+  ]
+}

package/harness.config.example.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "./schemas/harness-config.schema.json",
+  "project": {
+    "name": "Example Project",
+    "slug": "example-project",
+    "harnessRepoName": "example-structor"
+  },
+  "output": {
+    "path": "../example-structor"
+  },
+  "models": {
+    "openai": true,
+    "anthropic": true
+  },
+  "clientSupport": {
+    "codex": {
+      "hooks": true
+    },
+    "claude": {
+      "rules": true,
+      "hooks": false,
+      "skills": false
+    }
+  },
+  "consumers": [
+    {
+      "name": "example-app",
+      "path": "../example-app",
+      "purpose": "Primary application repository",
+      "validation": {
+        "install": "npm install",
+        "lint": "npm run lint",
+        "test": "npm test",
+        "build": "npm run build"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@structor-dev/cli",
+  "version": "0.1.0",
+  "description": "Harness-engineering toolkit that generates repository-local AI engineering harnesses for consumer repos.",
+  "license": "MIT",
+  "author": "Nicolay Camacho",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wari1986/structor.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "codex",
+    "claude-code",
+    "harness",
+    "governance",
+    "scaffolding"
+  ],
+  "type": "module",
+  "bin": {
+    "structor": "bin/structor.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "docs/",
+    "examples/",
+    "harness.config.example.json",
+    "schemas/",
+    "scripts/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npm run validate",
+    "check:ci": "node scripts/check-config.mjs && node scripts/check-template-files.mjs && node scripts/check-task-template.mjs && node scripts/check-contract-manifests.mjs && node scripts/check-model-overlays.mjs && node scripts/check-placeholders.mjs",
+    "check:config": "node scripts/check-config.mjs",
+    "check:placeholders": "node scripts/check-placeholders.mjs",
+    "check:templates": "node scripts/check-template-files.mjs",
+    "check:task-template": "node scripts/check-task-template.mjs",
+    "check:contracts": "node scripts/check-contract-manifests.mjs",
+    "check:model-overlays": "node scripts/check-model-overlays.mjs",
+    "check:smoke": "node scripts/smoke-template.mjs",
+    "validate": "npm run check:ci && npm run test && npm run check:smoke",
+    "validate:governance": "node scripts/validate-governance.mjs",
+    "init": "node bin/structor.mjs init",
+    "generate": "node bin/structor.mjs generate",
+    "init:harness": "node scripts/init-harness.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/schemas/contract-manifest.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/contract-manifest.schema.json",
+  "title": "Contract Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "version", "owners", "affectedRepos", "requiredFiles"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "owners": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "affectedRepos": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "requiredFiles": { "type": "array", "items": { "type": "string" } },
+    "forbiddenTokens": { "type": "array", "items": { "type": "string" } },
+    "validation": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/harness-config.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/harness-config.schema.json",
+  "title": "Harness Config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["project", "output", "models", "consumers"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "slug", "harnessRepoName"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "harnessRepoName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 }
+      }
+    },
+    "models": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["openai", "anthropic"],
+      "properties": {
+        "openai": { "type": "boolean" },
+        "anthropic": { "type": "boolean" }
+      }
+    },
+    "clientSupport": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "codex": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "hooks": { "type": "boolean" }
+          }
+        },
+        "claude": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "rules": { "type": "boolean" },
+            "hooks": { "const": false },
+            "skills": { "const": false }
+          }
+        }
+      }
+    },
+    "consumers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "path", "purpose", "validation"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "path": { "type": "string", "minLength": 1 },
+          "purpose": { "type": "string", "minLength": 1 },
+          "validation": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "install": { "type": "string" },
+              "lint": { "type": "string" },
+              "test": { "type": "string" },
+              "build": { "type": "string" },
+              "health": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/task-brief.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/task-brief.schema.json",
+  "title": "Task Brief",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "status",
+    "risk",
+    "autonomy",
+    "model_policy",
+    "model",
+    "repos",
+    "allowed_paths",
+    "forbidden_paths",
+    "requires_human_approval"
+  ],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "status": {
+      "type": "string",
+      "enum": ["backlog", "ready", "running", "needs_fix", "report_ready", "pr_ready", "blocked", "done"]
+    },
+    "risk": { "type": "string", "enum": ["low", "medium", "high"] },
+    "autonomy": { "type": "string", "enum": ["report_only", "pr_ready", "auto_merge"] },
+    "model_policy": {
+      "type": "string",
+      "enum": ["cheap", "standard", "reasoning", "frontier", "review_only"]
+    },
+    "model": { "type": "string", "minLength": 1 },
+    "repos": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "allowed_paths": { "type": "array", "items": { "type": "string" } },
+    "forbidden_paths": { "type": "array", "items": { "type": "string" } },
+    "requires_human_approval": { "type": "boolean" }
+  }
+}

package/scripts/check-config.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import {
+  assertSafeOutputRoot,
+  collectFiles,
+  exists,
+  failIfErrors,
+  readJson,
+  repoRoot,
+  validateConfigShape,
+} from "./lib.mjs";
+
+const errors = [];
+const args = process.argv.slice(2);
+const configArgIndex = args.indexOf("--config");
+const requireExistingConsumers = args.includes("--require-existing-consumers");
+const allowAbsoluteOutput = args.includes("--allow-absolute-output");
+const checkingExamples = configArgIndex === -1;
+const configFiles = checkingExamples
+  ? ["harness.config.example.json", ...(await collectFiles("examples", (file) => file.endsWith("harness.config.json")))]
+  : [path.resolve(args[configArgIndex + 1])];
+
+for (const configPath of configFiles) {
+  const label = checkingExamples ? configPath : path.relative(process.cwd(), configPath);
+  const config = checkingExamples
+    ? await readJson(configPath)
+    : JSON.parse(await readFile(configPath, "utf8"));
+  errors.push(...(await validateConfigShape(config, label)));
+
+  if (checkingExamples && path.isAbsolute(config.output?.path ?? "")) {
+    errors.push(`${label}: output.path must be relative for examples.`);
+  }
+  if (!checkingExamples) {
+    const configDir = path.dirname(configPath);
+    const outputPath = config.output.path;
+    const outputRoot = path.resolve(configDir, outputPath);
+    const consumerRepos = Array.isArray(config.consumers)
+      ? config.consumers.map((consumer) => path.resolve(configDir, consumer.path))
+      : [];
+    try {
+      assertSafeOutputRoot({
+        outputPath,
+        outputRoot,
+        repoRoot,
+        workspaceRoot: configDir,
+        consumerRepos,
+        allowAbsoluteOutput,
+      });
+    } catch (error) {
+      errors.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  if (Array.isArray(config.consumers)) {
+    for (const consumer of config.consumers) {
+      if (checkingExamples && path.isAbsolute(consumer.path)) {
+        errors.push(`${label}: consumer path for ${consumer.name} must be relative in checked-in examples.`);
+      }
+      if (requireExistingConsumers) {
+        const configDir = checkingExamples ? path.dirname(path.join(repoRoot, configPath)) : path.dirname(configPath);
+        const consumerPath = path.resolve(configDir, consumer.path);
+        if (!(await exists(consumerPath))) {
+          errors.push(`${label}: consumer path for ${consumer.name} does not exist: ${consumerPath}`);
+        }
+      }
+    }
+  }
+}
+
+if (repoRoot.endsWith("structor") === false) {
+  errors.push("repository folder should be named structor.");
+}
+
+failIfErrors("Config check", errors);

package/scripts/check-contract-manifests.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { failIfErrors, repoRoot } from "./lib.mjs";
+
+const contractsDirectory = "template/ai/contracts";
+const contractsReadmePath = `${contractsDirectory}/README.md.tpl`;
+const contractTemplateSuffix = ".contract.json.tpl";
+const docTemplateSuffix = ".md.tpl";
+const requiredFields = ["id", "name", "version", "owners", "affectedRepos", "requiredFiles"];
+const semverPattern = /^\d+\.\d+\.\d+$/;
+const placeholderStart = "{".repeat(2);
+const harnessRepoPlaceholder = `${placeholderStart}HARNESS_REPO_NAME}}`;
+const consumerReposPlaceholder = `${placeholderStart}CONSUMER_REPO_NAMES_JSON}}`;
+
+function renderTemplate(content) {
+  return content
+    .replaceAll(harnessRepoPlaceholder, "template-harness")
+    .replaceAll(consumerReposPlaceholder, JSON.stringify(["consumer-app"]));
+}
+
+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");
+
+const docFiles = entries
+  .filter((entry) => entry.isFile() && entry.name.endsWith(docTemplateSuffix) && entry.name !== "README.md.tpl")
+  .map((entry) => entry.name);
+for (const docName of docFiles) {
+  const linkedName = docName.replace(docTemplateSuffix, ".md");
+  if (!readme.includes(linkedName)) {
+    errors.push(`${contractsDirectory}/${docName} is not linked from ${contractsReadmePath}.`);
+  }
+}
+
+const contractFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(contractTemplateSuffix));
+for (const entry of contractFiles) {
+  const relativePath = `${contractsDirectory}/${entry.name}`;
+  const content = await readFile(path.join(repoRoot, relativePath), "utf8");
+  if (content.includes(placeholderStart)) {
+    const rendered = renderTemplate(content);
+    try {
+      const manifest = JSON.parse(rendered);
+      validateManifest(manifest, relativePath, errors);
+    } catch (error) {
+      errors.push(`${relativePath} must render to valid JSON before generation.`);
+      continue;
+    }
+  } else {
+    try {
+      const manifest = JSON.parse(content);
+      validateManifest(manifest, relativePath, errors);
+    } catch {
+      errors.push(`${relativePath} must be valid JSON.`);
+    }
+  }
+
+  const docPath = `${relativePath.replace(contractTemplateSuffix, docTemplateSuffix)}`;
+  if (!(await readFile(path.join(repoRoot, docPath), "utf8").catch(() => null))) {
+    errors.push(`${relativePath} must have a sibling ${docPath}.`);
+  }
+}
+
+failIfErrors("Contract manifest check", errors);

package/scripts/check-model-overlays.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { failIfErrors, repoRoot } from "./lib.mjs";
+
+const overlayFiles = [
+  "template/ai/model-overlays/openai/AGENTS.md.tpl",
+  "template/ai/model-overlays/anthropic/CLAUDE.md.tpl",
+  "template/consumer/AGENTS.md.tpl",
+  "template/consumer/CLAUDE.md.tpl",
+  "template/consumer/.claude/CLAUDE.md.tpl",
+  "template/.claude/CLAUDE.md.tpl",
+];
+const errors = [];
+
+for (const relativePath of overlayFiles) {
+  const content = await readFile(path.join(repoRoot, relativePath), "utf8");
+  if (!/canonical policy belongs|Canonical policy lives|Read the harness first|Read:/i.test(content)) {
+    errors.push(`${relativePath} must route to canonical policy.`);
+  }
+  if (!/thin|short|pointer/i.test(content)) {
+    errors.push(`${relativePath} must state that it stays thin or short.`);
+  }
+  if (content.length > 1200) {
+    errors.push(`${relativePath} is too large for a thin pointer file.`);
+  }
+}
+
+failIfErrors("Model overlay check", errors);

package/scripts/check-placeholders.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { collectFiles, failIfErrors, repoRoot } from "./lib.mjs";
+
+const errors = [];
+const activeFiles = await collectFiles(".", (file) => {
+  if (file.startsWith(".git/")) return false;
+  if (file.startsWith("template/")) return false;
+  return [".md", ".json", ".mjs"].some((suffix) => file.endsWith(suffix));
+});
+
+// Structor ships with no hardcoded project terms. Consumers can opt into this
+// leak check with a comma-separated HARNESS_FORBIDDEN_PROJECT_TERMS value.
+const forbiddenProjectTermsEnvVar = "HARNESS_FORBIDDEN_PROJECT_TERMS";
+const termListSeparator = ",";
+
+const configuredForbiddenProjectTerms = (process.env[forbiddenProjectTermsEnvVar] ?? "")
+  .split(termListSeparator)
+  .map((term) => term.trim())
+  .filter(Boolean);
+
+const forbiddenProjectTerms = [...new Set(configuredForbiddenProjectTerms)]
+  .map((term) => new RegExp(`\\b${escapeRegExp(term)}\\b`, "i"));
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+for (const relativePath of activeFiles) {
+  const content = await readFile(path.join(repoRoot, relativePath), "utf8");
+  if (/\{\{[A-Z0-9_]+\}\}/.test(content)) {
+    errors.push(`${relativePath} contains an unresolved template placeholder.`);
+  }
+  if (relativePath !== "scripts/check-placeholders.mjs" && /TODO|TBD|fixme/i.test(content)) {
+    errors.push(`${relativePath} contains TODO/TBD/fixme placeholder text.`);
+  }
+  if (relativePath === "scripts/check-placeholders.mjs") continue;
+  for (const pattern of forbiddenProjectTerms) {
+    if (pattern.test(content)) {
+      errors.push(`${relativePath} contains a configured forbidden project term.`);
+      break;
+    }
+  }
+}
+
+failIfErrors("Placeholder check", errors);

package/scripts/check-task-template.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { failIfErrors, repoRoot } from "./lib.mjs";
+
+const relativePath = "template/ai/templates/task-brief-template.md.tpl";
+const content = await readFile(path.join(repoRoot, relativePath), "utf8");
+const requiredSections = [
+  "## Summary",
+  "## Context",
+  "## Goals",
+  "## Non-Goals",
+  "## Scope",
+  "## Path Contract",
+  "## Requirements",
+  "## Bootstrap Requirements",
+  "## Proposed Approach",
+  "## Agent Execution Protocol",
+  "## Success Criteria",
+  "## Validation",
+  "## Validation Evidence Required",
+  "## Risk and Autonomy",
+  "## Review Routing",
+  "## Dependencies",
+  "## Rollback / Recovery",
+  "## Open Questions",
+  "## Notes for the Agent",
+];
+const requiredFrontmatter = [
+  "id:",
+  "status:",
+  "risk:",
+  "autonomy:",
+  "model_policy:",
+  "model:",
+  "repos:",
+  "allowed_paths:",
+  "forbidden_paths:",
+  "requires_human_approval:",
+];
+
+const errors = [];
+for (const token of [...requiredSections, ...requiredFrontmatter]) {
+  if (!content.includes(token)) errors.push(`${relativePath} is missing ${token}`);
+}
+
+const modelLine = content.split("\n").find((line) => line.startsWith("model:"));
+if (modelLine && /\b(?:gpt-|claude|opus|sonnet|haiku)/i.test(modelLine)) {
+  errors.push(`${relativePath} must use a runtime-neutral model selector, not a concrete provider model.`);
+}
+
+failIfErrors("Task template check", errors);