@juangcarmona/lighthouse 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Lighthouse CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package is the core Lighthouse harness. It provides the `lighthouse` command, the manifest schema and the generated `LIGHTHOUSE.md` projection.
+
+## Initialize a repository
+
+Install the exact Lighthouse package artifacts selected for the release, create the project manifest and run `lighthouse init`. Inspect the generated `LIGHTHOUSE.md`, then run `lighthouse verify` before adding project-specific policy or exceptions.
+
+The harness package owns the baseline command and verification contract. The SDLC package owns lifecycle skills, commands and metacommands. The UI package owns visual tokens, native recipes and `DESIGN.md`. Stack profiles own their source templates, guidance and checks.
+
+ProductShape, ArcShape and OpenSpec keep their own files and commands. Add them through their supported integration routes when the project needs them, and keep their versions and managed paths visible in the project configuration.
+
+## New repository
+
+1. Select the harness, SDLC, UI and stack profile artifacts required by the application.
+2. Create the manifest with exact package and integration versions.
+3. Run `lighthouse init`, review the generated projection and run `lighthouse verify`.
+4. Add the selected profile checks to the repository verification command and CI workflow.
+5. Record project-owned exceptions with an owner and review date.
+
+## Existing repository
+
+1. Inventory the current source layout, tools, managed files and CI before editing.
+2. Map existing files to the selected Lighthouse contracts and identify collisions.
+3. Adopt the manifest and verifier first; preserve product-owned guidance and generated outputs.
+4. Add profiles one at a time and measure their checks before making a workflow status required.
+5. Record each exception in the project-owned documentation and remove it when the product is ready.
+
+## Current command scope
+
+The current command supports `init` and `verify`. It checks the manifest, exact version pins and generated content. Lifecycle stages, tracker operations, agent runs and CodeGraph checks require their own configured integrations.
+
+The package does not contain the repository gallery, provider-owned integrations or reference source. Those remain with the source repository or the profile that owns them.

package/assets/schemas/lighthouse-manifest.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-manifest.schema.json",
+  "title": "Lighthouse repository manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "baseline", "product", "profiles", "integrations", "managed"],
+  "properties": {
+    "$schema": {"type": "string"},
+    "schemaVersion": {"const": 1},
+    "baseline": {"const": "0.1.0"},
+    "product": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$"},
+    "profiles": {"type": "array", "items": {"enum": ["node-tooling", "dotnet-backend", "visual-theme"]}, "uniqueItems": true},
+    "integrations": {"type": "object", "additionalProperties": false, "required": ["productShape", "arcShape", "agenticSdlc"], "properties": {"productShape": {"$ref": "#/$defs/pin"}, "arcShape": {"$ref": "#/$defs/pin"}, "agenticSdlc": {"$ref": "#/$defs/pin"}}},
+    "managed": {"const": ["LIGHTHOUSE.md"]}
+  },
+  "$defs": {
+    "pin": {"type": ["string", "null"], "pattern": "^(?:\\d+\\.\\d+\\.\\d+|[a-f0-9]{40})$"}
+  }
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Lighthouse adoption and verification CLI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juangcarmona/lighthouse.git",
+    "directory": "src/packages/cli"
+  },
+  "homepage": "https://juangcarmona.github.io/lighthouse/",
+  "bugs": {
+    "url": "https://github.com/juangcarmona/lighthouse/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": ["src/lighthouse.mjs", "assets", "README.md"],
+  "bin": {
+    "lighthouse": "./src/lighthouse.mjs"
+  }
+}

package/src/lighthouse.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const root = process.cwd();
+const manifestPath = resolve(root, 'lighthouse.json');
+const projection = 'LIGHTHOUSE.md';
+const usage = 'Usage: lighthouse <init|verify>';
+
+function render(manifest) {
+  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Agentic SDLC: ${manifest.integrations.agenticSdlc ?? 'not adopted'}\n\n## How delivery works\n\nUse ProductShape for product intent and Product Changes, and use ArcShape for applicable architecture decisions; they can advance independently. Lighthouse carries the selected authority context through the delivery stages.\n\nA greenfield project initializes both authorities through their supported provider routes. An existing project can adopt them incrementally after its ownership and managed paths are assessed. The adoption contract includes a check of the external CodeGraph MCP service, its current git-root binding and the canonical repository and active worktrees; its index and credentials stay outside the checkout.\n\n1. \`triage\` classifies the work item, estimates complexity and blast radius, records urgency, impact, dependencies and risk, and sets configured workflow labels.\n2. \`refine\` defines the problem and stops at Ready.\n3. \`propose\` creates the solution and stops at Planned.\n4. \`implement\` applies the accepted plan and stops at Done.\n5. \`integrate\` updates the tracker, maintains the PR stack and closes the repository loop.\n6. \`review\` records learning after completion.\n\nThese are lifecycle capabilities. The baseline CLI currently provides \`init\` and \`verify\`; a configured OpenSpec, tracker or agent-host integration supplies the stage commands.\n\nChoose supervised work when a person steers each stage, plan-only work when only the proposal is needed, \`ff\` for a bounded unattended route, \`hotfix\` for a confirmed defect or \`decompose\` for a large item that needs ordered child issues and stacked PRs.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
+}
+
+function validate(m) {
+  const problems = [];
+  if (!m || typeof m !== 'object' || Array.isArray(m)) return ['manifest must be an object'];
+  const allowed = ['$schema', 'schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'managed'];
+  for (const key of Object.keys(m)) if (!allowed.includes(key)) problems.push(`unknown field ${key}`);
+  for (const key of ['schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'managed']) if (!(key in m)) problems.push(`missing ${key}`);
+  if (m.schemaVersion !== 1) problems.push('schemaVersion must be 1');
+  if (m.baseline !== '0.1.0') problems.push('this verifier supports baseline 0.1.0');
+  if ('$schema' in m && typeof m.$schema !== 'string') problems.push('$schema must be a string');
+  if (typeof m.product !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(m.product)) problems.push('product must be a readable name of 1–64 characters');
+  const profiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
+  if (!Array.isArray(m.profiles) || m.profiles.some((p) => !profiles.includes(p)) || new Set(m.profiles).size !== m.profiles.length) problems.push('profiles must be unique supported profile names');
+  const integrations = m.integrations;
+  const keys = ['productShape', 'arcShape', 'agenticSdlc'];
+  const pin = /^(?:\d+\.\d+\.\d+|[a-f0-9]{40})$/;
+  if (!integrations || typeof integrations !== 'object' || Array.isArray(integrations)
+      || Object.keys(integrations).length !== keys.length
+      || keys.some((k) => !(k in integrations) || (integrations[k] !== null && (typeof integrations[k] !== 'string' || !pin.test(integrations[k])))))
+    problems.push('integrations must declare productShape, arcShape and agenticSdlc as exact versions, commit hashes or null');
+  if (!Array.isArray(m.managed) || m.managed.length !== 1 || m.managed[0] !== projection) problems.push(`only ${projection} is managed by this version`);
+  return problems;
+}
+
+const command = process.argv[2];
+if (!['init', 'verify'].includes(command)) { console.error(usage); process.exit(2); }
+let manifest;
+try { manifest = JSON.parse(await readFile(manifestPath, 'utf8')); }
+catch (error) { console.error(`Cannot read lighthouse.json: ${error.message}`); process.exit(1); }
+const problems = validate(manifest);
+if (problems.length) { console.error(problems.map((p) => `Invalid lighthouse.json: ${p}`).join('\n')); process.exit(1); }
+const expected = render(manifest);
+const target = resolve(root, projection);
+if (command === 'init') {
+  try { await readFile(target); console.error(`${projection} already exists; refusing to overwrite it. Review the manifest and manage the file explicitly.`); process.exit(1); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  await writeFile(target, expected, { flag: 'wx' });
+  console.log(`Created ${projection} from lighthouse.json.`);
+} else {
+  try {
+    const actual = await readFile(target, 'utf8');
+    if (actual !== expected) { console.error(`${projection} has drifted. Regenerate it from lighthouse.json or restore the generated content.`); process.exit(1); }
+  } catch (error) {
+    if (error.code === 'ENOENT') { console.error(`${projection} is missing; run lighthouse init after reviewing the manifest.`); process.exit(1); }
+    throw error;
+  }
+  console.log('Lighthouse manifest and managed projection are valid.');
+}