@juangcarmona/lighthouse 0.6.0 → 0.8.0

package/assets/schemas/profile-catalog.schema.json

@@ -4,59 +4,325 @@
   "title": "Lighthouse profile catalog",
   "type": "object",
   "additionalProperties": false,
-  "required": ["$schema", "schemaVersion", "profiles"],
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "profiles"
+  ],
   "properties": {
-    "$schema": { "type": "string" },
-    "schemaVersion": { "const": 1 },
+    "$schema": {
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": 1
+    },
     "profiles": {
       "type": "array",
-      "items": { "$ref": "#/$defs/profile" }
+      "items": {
+        "$ref": "#/$defs/profile"
+      }
     }
   },
   "$defs": {
     "profile": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["id", "owner", "purpose", "appliesTo", "surfaces", "verification"],
+      "required": [
+        "id",
+        "owner",
+        "purpose",
+        "appliesTo",
+        "surfaces",
+        "prerequisites",
+        "dependencies",
+        "incompatibleWith",
+        "libraries",
+        "structure",
+        "commands",
+        "guardrails",
+        "failureConsequence",
+        "repairHints",
+        "exceptions",
+        "combinations",
+        "consumerFixture",
+        "upgradeStrategy",
+        "verification"
+      ],
       "properties": {
-        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
-        "owner": { "type": "string", "minLength": 1 },
-        "purpose": { "type": "string", "minLength": 1 },
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1
+        },
         "appliesTo": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["shapes", "stacks"],
+          "required": [
+            "shapes",
+            "stacks"
+          ],
           "properties": {
-            "shapes": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true },
-            "stacks": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+            "shapes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "stacks": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "uniqueItems": true
+            }
           }
         },
-        "surfaces": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true },
+        "surfaces": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
         "verification": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["layers"],
+          "required": [
+            "layers"
+          ],
           "properties": {
             "layers": {
               "type": "array",
-              "items": { "$ref": "#/$defs/layer" },
+              "items": {
+                "$ref": "#/$defs/layer"
+              },
               "minItems": 1,
               "uniqueItems": true
             }
           }
+        },
+        "prerequisites": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/profileId"
+          },
+          "uniqueItems": true
+        },
+        "incompatibleWith": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/profileId"
+          },
+          "uniqueItems": true
+        },
+        "libraries": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "structure": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "commands": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "guardrails": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/guardrail"
+          },
+          "uniqueItems": true
+        },
+        "failureConsequence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repairHints": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "exceptions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "combinations": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/combination"
+          },
+          "uniqueItems": true
+        },
+        "consumerFixture": {
+          "type": "string",
+          "minLength": 1
+        },
+        "upgradeStrategy": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },
     "layer": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["id", "level", "kind", "verification"],
+      "required": [
+        "id",
+        "level",
+        "kind",
+        "verification"
+      ],
       "properties": {
-        "id": { "enum": ["static", "unit", "architecture", "integration", "functional", "browser-e2e", "operational"] },
-        "level": { "enum": ["required", "recommended", "optional"] },
-        "kind": { "enum": ["hard", "soft"] },
-        "verification": { "enum": ["deterministic", "semantic", "human"] },
-        "command": { "type": ["string", "null"] }
+        "id": {
+          "enum": [
+            "static",
+            "unit",
+            "architecture",
+            "integration",
+            "functional",
+            "browser-e2e",
+            "operational"
+          ]
+        },
+        "level": {
+          "enum": [
+            "required",
+            "recommended",
+            "optional"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "hard",
+            "soft"
+          ]
+        },
+        "verification": {
+          "enum": [
+            "deterministic",
+            "semantic",
+            "human"
+          ]
+        },
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "profileId": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "guardrail": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "level",
+        "kind",
+        "verification",
+        "command",
+        "description"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "level": {
+          "enum": [
+            "required",
+            "recommended",
+            "optional"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "hard",
+            "soft"
+          ]
+        },
+        "verification": {
+          "enum": [
+            "deterministic",
+            "semantic",
+            "human"
+          ]
+        },
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "combination": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "with",
+        "purpose"
+      ],
+      "properties": {
+        "with": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/profileId"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1
+        }
       }
     }
   }

package/assets/skills/init/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: lighthouse-init
+description: Turn a natural-language project request into a reviewable Lighthouse initialization plan.
+---
+
+# Lighthouse semantic initialization
+
+Use this skill when an adopter describes a project in product terms and wants Lighthouse to prepare its foundation.
+
+## Inputs
+
+1. Read the installed profile catalog and the repository's current Lighthouse manifest when one exists.
+2. Treat a reference project as optional. If the adopter names one, record its location and purpose; do not assume it exists or copy it.
+3. Ask only the questions needed to resolve the application shape, stacks, profiles and material profile combinations. Keep unresolved questions in the plan instead of guessing.
+
+## Plan
+
+Write a JSON plan that validates against `assets/schemas/init-plan.schema.json` with `schemaVersion: 1`, `product`, `intent`, `application`, `profiles`, optional `reference` metadata and `openQuestions`.
+
+Select profiles from the installed catalog. Do not invent a profile, make a stack mandatory, or turn a reference into a requirement. An absent reference is represented by an omitted `reference` field or `{"kind":"none"}`.
+
+## Apply
+
+Review the generated plan with the adopter, then run `lighthouse init --plan-file <path>` for a dry run. Use `--format json` for agent consumption. Apply only after the adopter explicitly authorizes `lighthouse init --plan-file <path> --apply`.
+
+The CLI owns deterministic validation, profile compatibility, conflict detection and local writes. It does not inspect or copy the reference and it performs no remote writes. A plan with `openQuestions` is not ready to apply.
+
+Use `lighthouse aliases --format json` to discover the installed `/lh:*` aliases and their canonical `/lighthouse:*` commands. The generated `.lighthouse/commands.json` is the host-readable projection; aliases reference the package-owned command or skill asset and never create a second implementation.
+
+After applying, run `lighthouse verify` and report the created, preserved and conflicting paths. Keep product and architecture work in ProductShape and ArcShape's own routes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -20,13 +20,15 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@arcshape/cli": "0.1.3",
+    "@arcshape/cli": "0.1.4",
     "@juangcarmona/lighthouse-ui": "0.2.0",
     "@prodshape/cli": "0.22.0",
-    "@juangcarmona/lighthouse-sdlc": "0.6.0"
+    "@juangcarmona/lighthouse-sdlc": "0.7.0"
   },
   "files": [
     "src/lighthouse.mjs",
+    "src/aliases.mjs",
+    "src/init-plan.mjs",
     "src/guardrails.mjs",
     "assets",
     "README.md",

package/src/aliases.mjs

@@ -0,0 +1,56 @@
+import { access } from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contractPath = resolve(packageRoot, 'assets/command-aliases.json');
+const packageName = '@juangcarmona/lighthouse';
+const aliasPattern = /^\/lh:[a-z][a-z0-9-]*$/u;
+const canonicalPattern = /^\/lighthouse:[a-z][a-z0-9-]*$/u;
+const assetPattern = /^skills\/[a-z0-9-]+\/SKILL\.md$/u;
+
+async function exists(path) {
+  try { await access(path, constants.F_OK); return true; } catch { return false; }
+}
+
+export function readCommandAliases(path = contractPath) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function validateCommandAliases(contract) {
+  const errors = [];
+  if (!contract || typeof contract !== 'object' || Array.isArray(contract)) return [{ code: 'aliases.invalid', message: 'command alias contract must be an object' }];
+  if (contract.schemaVersion !== 1) errors.push({ code: 'aliases.schema-version', message: 'command alias schemaVersion must be 1' });
+  if (contract.contractVersion !== 1) errors.push({ code: 'aliases.contract-version', message: 'command alias contractVersion must be 1' });
+  if (contract.package?.name !== packageName) errors.push({ code: 'aliases.package', message: `command alias contract package must be ${packageName}` });
+  if (contract.canonicalNamespace !== '/lighthouse') errors.push({ code: 'aliases.canonical-namespace', message: 'canonical namespace must be /lighthouse' });
+  if (contract.aliasNamespace !== '/lh') errors.push({ code: 'aliases.alias-namespace', message: 'alias namespace must be /lh' });
+  if (!Array.isArray(contract.aliases) || contract.aliases.length === 0) return [...errors, { code: 'aliases.list', message: 'command alias contract must declare at least one alias' }];
+  const aliases = new Set();
+  const canonicals = new Set();
+  for (const [index, item] of contract.aliases.entries()) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      errors.push({ code: 'aliases.entry', message: `alias ${index} must be an object` });
+      continue;
+    }
+    if (typeof item.alias !== 'string' || !aliasPattern.test(item.alias)) errors.push({ code: 'aliases.alias', message: `alias ${index} must use the /lh:<verb> form` });
+    if (typeof item.canonical !== 'string' || !canonicalPattern.test(item.canonical)) errors.push({ code: 'aliases.canonical', message: `alias ${index} must target a /lighthouse:<verb> command` });
+    if (typeof item.asset !== 'string' || !assetPattern.test(item.asset)) errors.push({ code: 'aliases.asset', message: `alias ${index} must reference a packaged skill asset` });
+    if (aliases.has(item.alias)) errors.push({ code: 'aliases.duplicate', message: `alias ${item.alias} is declared more than once` });
+    if (canonicals.has(item.canonical)) errors.push({ code: 'aliases.duplicate-target', message: `canonical command ${item.canonical} has more than one alias` });
+    aliases.add(item.alias);
+    canonicals.add(item.canonical);
+  }
+  return errors;
+}
+
+export async function verifyCommandAliases(contract = readCommandAliases()) {
+  const errors = validateCommandAliases(contract);
+  for (const item of contract.aliases ?? []) {
+    if (typeof item.asset === 'string' && !(await exists(resolve(packageRoot, 'assets', item.asset)))) errors.push({ code: 'aliases.missing-asset', message: `alias ${item.alias} references missing asset ${item.asset}` });
+  }
+  return errors;
+}
+
+export { contractPath };

package/src/create-dotnet.mjs

@@ -74,19 +74,23 @@ try {
   await writeFile(solutionFile, `<Solution>\n${projects.map((project) => `  ${project}`).join('\n')}\n</Solution>\n`);
 
   await copy(resolve(packageRoot, 'src/lighthouse.mjs'), resolve(stage, 'scripts/lighthouse.mjs'));
+  await copy(resolve(packageRoot, 'src/aliases.mjs'), resolve(stage, 'scripts/aliases.mjs'));
+  await copy(resolve(packageRoot, 'src/init-plan.mjs'), resolve(stage, 'scripts/init-plan.mjs'));
   await copy(resolve(packageRoot, 'src/guardrails.mjs'), resolve(stage, 'scripts/guardrails.mjs'));
   await copy(resolve(packageRoot, 'src/profiles.mjs'), resolve(stage, 'scripts/profiles.mjs'));
   await copy(resolve(packageRoot, 'src/verify-dotnet.mjs'), resolve(stage, 'scripts/verify-dotnet.mjs'));
   await copy(resolve(packageRoot, 'assets/guardrails'), resolve(stage, 'assets/guardrails'));
   await copy(resolve(packageRoot, 'assets/profiles'), resolve(stage, 'assets/profiles'));
   await copy(resolve(packageRoot, 'assets/schemas'), resolve(stage, 'schemas'));
+  await copy(resolve(packageRoot, 'assets/command-aliases.json'), resolve(stage, 'assets/command-aliases.json'));
+  await copy(resolve(packageRoot, 'assets/skills/init'), resolve(stage, 'assets/skills/init'));
 
   await writeFile(resolve(stage, 'lighthouse.json'), `${JSON.stringify({
     $schema: './schemas/lighthouse-manifest.schema.json', schemaVersion: 1, baseline: '0.1.0',
     product: name, application: { shape: 'backend', stacks: ['dotnet'] }, profiles: ['dotnet-backend'],
     integrations: { productShape: null, arcShape: null },
     packages: { sdlc: { name: '@juangcarmona/lighthouse-sdlc', version: sdlcContract.version } },
-    managed: ['LIGHTHOUSE.md', 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', '.lighthouse/upgrade.json', 'docs/profiles/dotnet/README.md', 'docs/profiles/dotnet/adoption.md', 'docs/profiles/dotnet/architecture.md', 'docs/profiles/dotnet/guardrails.md', 'docs/profiles/dotnet/practices.md', 'docs/profiles/dotnet/testing-and-development.md', 'docs/profiles/dotnet/use-cases.md', '.agents/skills/lighthouse-dotnet/SKILL.md'],
+    managed: ['LIGHTHOUSE.md', 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', '.agents/skills/lighthouse-init/SKILL.md', '.lighthouse/upgrade.json', '.lighthouse/commands.json', 'docs/profiles/dotnet/README.md', 'docs/profiles/dotnet/adoption.md', 'docs/profiles/dotnet/architecture.md', 'docs/profiles/dotnet/guardrails.md', 'docs/profiles/dotnet/practices.md', 'docs/profiles/dotnet/testing-and-development.md', 'docs/profiles/dotnet/use-cases.md', '.agents/skills/lighthouse-dotnet/SKILL.md'],
     repository: {
       layout: ['src', 'docs', 'infra', 'scripts'], publicSite: { enabled: true },
       conventions: { commits: 'conventional', branchPattern: '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$' },

package/src/init-plan.mjs

@@ -0,0 +1,62 @@
+const productNamePattern = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/u;
+const shapes = new Set(['unknown', 'frontend', 'backend', 'full-stack', 'service', 'library', 'tooling', 'cli', 'worker', 'mobile']);
+const referenceKinds = new Set(['none', 'local', 'repository']);
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function uniqueStrings(value, name, { required = false } = {}) {
+  if (!Array.isArray(value) || (required && value.length === 0) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    return [`${name} must contain non-empty strings`];
+  }
+  return new Set(value).size === value.length ? [] : [`${name} must be unique`];
+}
+
+function referenceProblems(reference) {
+  if (reference === undefined || reference === null) return [];
+  if (!isObject(reference)) return ['reference must be null or an object'];
+  const problems = [];
+  if (!referenceKinds.has(reference.kind)) problems.push('reference.kind must be none, local or repository');
+  if (reference.kind !== 'none' && (typeof reference.location !== 'string' || reference.location.length === 0)) {
+    problems.push('reference.location is required for local and repository references');
+  }
+  if (reference.kind === 'none' && 'location' in reference) problems.push('reference.location is not allowed when reference.kind is none');
+  if ('purpose' in reference && (typeof reference.purpose !== 'string' || reference.purpose.length === 0)) problems.push('reference.purpose must be a non-empty string');
+  return problems;
+}
+
+export function validateInitPlan(plan, supportedProfiles) {
+  if (!isObject(plan)) return ['plan must be an object'];
+  const problems = [];
+  const allowed = new Set(['$schema', 'schemaVersion', 'product', 'intent', 'application', 'profiles', 'reference', 'openQuestions']);
+  for (const key of Object.keys(plan)) if (!allowed.has(key)) problems.push(`unknown field ${key}`);
+  if (plan.schemaVersion !== 1) problems.push('schemaVersion must be 1');
+  if (typeof plan.product !== 'string' || !productNamePattern.test(plan.product)) problems.push('product must be a readable name of 1–64 characters');
+  if (typeof plan.intent !== 'string' || plan.intent.trim().length === 0) problems.push('intent must be a non-empty string');
+  if (!isObject(plan.application)) problems.push('application must be an object');
+  else {
+    if (!shapes.has(plan.application.shape)) problems.push(`application.shape must be one of ${[...shapes].join(', ')}`);
+    problems.push(...uniqueStrings(plan.application.stacks, 'application.stacks'));
+  }
+  problems.push(...uniqueStrings(plan.profiles, 'profiles'));
+  for (const profile of plan.profiles ?? []) {
+    if (!supportedProfiles.includes(profile)) problems.push(`unknown profile ${profile}; use ${supportedProfiles.join(', ')}`);
+  }
+  problems.push(...referenceProblems(plan.reference));
+  problems.push(...uniqueStrings(plan.openQuestions, 'openQuestions'));
+  return problems;
+}
+
+export function hasUnresolvedQuestions(plan) {
+  return Array.isArray(plan.openQuestions) && plan.openQuestions.length > 0;
+}
+
+export function manifestFromInitPlan(plan, createManifest) {
+  const manifest = createManifest(plan.product, plan.profiles);
+  manifest.application = {
+    shape: plan.application.shape,
+    stacks: [...plan.application.stacks],
+  };
+  return manifest;
+}