@mriekki/project-forge 1.0.0 → 2.1.0

package/assets/generated/core/core/skills/run/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: run
+description: "Run the current project locally through its repository-owned runtime command without conflating local execution with deployment."
+argument-hint: "[target|all]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Run
+
+`/run` is the normal convenience entry point for starting the project locally. It resolves and delegates to repository-owned runtime commands rather than requiring the developer to remember framework-specific launch syntax.
+
+## Contract
+
+Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, deployment, release publication, Production access, or persistent background services outside the repository's normal local-development contract.
+
+Resolve the local runtime command from current repository evidence in this order:
+
+1. an explicit repository-owned run/dev wrapper or documented command;
+2. an explicit package/task script whose purpose is local run/dev;
+3. an unambiguous ecosystem-native local entry point already present in the repository.
+
+Do not guess. If the repository has multiple independent runtimes and no documented default, require a target such as `/run web`, `/run api`, or `/run all`.
+
+## Preconditions
+
+Before starting:
+
+- identify repository root and current Git state;
+- inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
+- verify the selected runtime entry point exists;
+- inspect any documented local ports/health endpoints;
+- do not create an intentionally deferred scaffold merely to make `/run` succeed.
+
+If runtime source is intentionally deferred or absent, return `RUN NOT AVAILABLE` and identify the owning work item or missing marker when repository evidence provides it.
+
+If workstation tools or dependencies are missing, recommend `/setup` instead of silently installing them.
+
+## Execution
+
+Start the process in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
+
+Report:
+
+- target;
+- resolved command identity;
+- process/startup result;
+- effective application release/build identity when the running application exposes it;
+- local URL/port or health evidence only when repository/runtime evidence establishes it;
+- how to stop the process.
+
+When `/run all` is explicitly supported, start only the repository-defined set of local components and make each process/endpoint visible.
+
+When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer runtime-observed version evidence over a source-file guess. Do not synthesize a build number or claim that a static source label proves the running artifact's identity.
+
+## Operation journal
+
+`/run` may write a concise sanitized startup receipt under `.project-forge/logs/run/` following `docs/process/OPERATION_JOURNAL.md`.
+
+Record startup command identity, target, timestamps, startup/health result, observed application version/build identity, and endpoint when established. Do not duplicate or continuously capture unbounded application stdout/stderr into the Project Forge journal.
+
+## Deployment boundary
+
+`/run` is not `/deploy local`.
+
+It must not:
+
+- mutate remote environments;
+- publish images/packages/releases;
+- change deployment bindings;
+- infer Production configuration;
+- bump or rewrite release version state;
+- stage, commit, push, merge, or clean branches.
+
+A successful `/run` proves only that the requested local runtime started with the evidence observed in that session.

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -24,7 +24,7 @@ From the repository root inspect only what is needed:
 
 - `DEV_ENVIRONMENT.json`;
 - `DEPLOYMENT_TOPOLOGY.json` when present;
-- `POC_BOOTSTRAP.json` as generation/provenance and initial topology fallback;
+- `PROJECT_BOOTSTRAP.json` as generation/provenance and initial topology fallback;
 - `SCAFFOLD_PLAN.json` when present;
 - `.github/project-forge-workspace.json` and Project Forge/component baselines when present;
 - `scripts/setup.ps1` on Windows or `scripts/setup.sh` on macOS;
@@ -167,9 +167,9 @@ Prefer project-owned mutable deployment topology:
 DEPLOYMENT_TOPOLOGY.json
 ```
 
-Use `POC_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
+Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
 
-`POC_BOOTSTRAP.json` is generation/provenance evidence and should not be casually rewritten merely because a developer adds an environment later.
+`PROJECT_BOOTSTRAP.json` is generation/provenance evidence and should not be casually rewritten merely because a developer adds an environment later.
 
 If an older POC has no `DEPLOYMENT_TOPOLOGY.json` and the developer chooses to add/change a logical environment, first materialize the currently approved deployment topology into the project-owned file, then make the scoped project configuration change there. Preserve the original Bootstrap provenance file.
 

package/assets/generated/core/core/skills/tear-down/SKILL.md

@@ -29,7 +29,7 @@ Prefer:
 DEPLOYMENT_TOPOLOGY.json
 ```
 
-Use `POC_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
+Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback.
 
 Resolve only configured logical environments and their current purpose/Production classification, placement/target binding, repository/application identity, and ownership evidence.
 

package/bin/project-forge.mjs

@@ -1,9 +1,9 @@
-#!/usr/bin/env node
-import { run } from '../src/cli.mjs';
-
-try {
-  process.exitCode = await run();
-} catch (error) {
-  console.error(`Project Forge error: ${error.message}`);
-  process.exitCode = 2;
-}
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+
+try {
+  process.exitCode = await run();
+} catch (error) {
+  console.error(`Project Forge error: ${error.message}`);
+  process.exitCode = 2;
+}

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "@mriekki/project-forge",
-  "version": "1.0.0",
-  "description": "Public consumer distribution and updater for Project Forge engineering assets.",
-  "type": "module",
-  "bin": {
-    "project-forge": "bin/project-forge.mjs"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "assets/",
-    "README.md"
-  ],
-  "scripts": {
-    "test": "node --test",
-    "assemble:assets": "node scripts/assemble-assets.mjs",
-    "verify:assets": "node scripts/verify-assets.mjs",
-    "release:prepare": "node scripts/prepare-release.mjs",
-    "prepack": "npm run verify:assets"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mriekki/project-forge-platform.git"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
-  }
-}
+{
+  "name": "@mriekki/project-forge",
+  "version": "2.1.0",
+  "description": "Public consumer distribution and updater for Project Forge engineering assets.",
+  "type": "module",
+  "bin": {
+    "project-forge": "bin/project-forge.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "assemble:assets": "node scripts/assemble-assets.mjs",
+    "verify:assets": "node scripts/verify-assets.mjs",
+    "release:prepare": "node scripts/prepare-release.mjs",
+    "prepack": "npm run verify:assets"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mriekki/project-forge-platform.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/cli.mjs

@@ -1,150 +1,150 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { execFileSync } from 'node:child_process';
-import readline from 'node:readline/promises';
-import { stdin as input, stdout as output } from 'node:process';
-import { applyProfile, checkProfile, loadProjectForgeBaseline, planProfile } from './engine.mjs';
-import { loadPackageData } from './package-data.mjs';
-
-function parseArgs(argv) {
-  const options = { acceptedRetired: new Map() };
-  const positional = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--help' || arg === '-h') options.help = true;
-    else if (arg === '--apply' || arg === '--yes') options.apply = true;
-    else if (arg === '--root') options.root = argv[++i];
-    else if (arg === '--profile') options.profile = argv[++i];
-    else if (arg === '--consumer') options.consumer = argv[++i];
-    else if (arg === '--consumer-baseline') options.consumerBaseline = argv[++i];
-    else if (arg === '--accept-retired') {
-      const value = argv[++i] ?? '';
-      const index = value.indexOf(':');
-      if (index <= 0) throw new Error('--accept-retired must use component:path');
-      const component = value.slice(0, index);
-      const retiredPath = value.slice(index + 1);
-      if (!options.acceptedRetired.has(component)) options.acceptedRetired.set(component, new Set());
-      options.acceptedRetired.get(component).add(retiredPath);
-    } else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
-    else positional.push(arg);
-  }
-  return { command: positional[0] ?? 'help', options };
-}
-
-function inferConsumer(root) {
-  try {
-    const origin = execFileSync('git', ['-C', root, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    if (origin) {
-      const normalized = origin.replace(/\\/g, '/').replace(/\.git$/, '');
-      const match = normalized.match(/[:/]([^/:]+\/[^/]+)$/);
-      if (match) return match[1].split('/').pop();
-    }
-  } catch {}
-  return path.basename(root);
-}
-
-function printPlan(plan) {
-  console.log(`Project Forge profile: ${plan.profileName}`);
-  for (const component of plan.plans) {
-    console.log(`\n${component.componentId.toUpperCase()} ${component.component.commit}`);
-    for (const row of component.rows) console.log(`${row.state.padEnd(20)} ${row.path}`);
-    for (const retired of component.retired) console.log(`${retired.state.padEnd(20)} ${retired.path}`);
-  }
-  console.log(`\nUnsafe drift/conflicts: ${plan.unsafe.length}`);
-  for (const item of plan.unsafe) console.log(`  - ${item.component}: ${item.state}: ${item.path}`);
-}
-
-async function shouldApply(options) {
-  if (options.apply) return true;
-  if (!input.isTTY || !output.isTTY) return false;
-  const rl = readline.createInterface({ input, output });
-  try {
-    const answer = (await rl.question('Apply this safe Project Forge asset plan? [y/N] ')).trim().toLowerCase();
-    return answer === 'y' || answer === 'yes';
-  } finally {
-    rl.close();
-  }
-}
-
-function usage(command) {
-  const commandUsage = {
-    install: 'project-forge install [--root PATH] [--profile NAME] [--apply|--yes] [--consumer NAME] [--consumer-baseline LABEL] [--accept-retired component:path]',
-    update: 'project-forge update [--root PATH] [--profile NAME] [--apply|--yes] [--accept-retired component:path]',
-    status: 'project-forge status [--root PATH] [--profile NAME]',
-    check: 'project-forge check [--root PATH] [--profile NAME]',
-    version: 'project-forge version'
-  };
-
-  if (commandUsage[command]) {
-    console.log(`@mriekki/project-forge\n\nUsage:\n  ${commandUsage[command]}\n`);
-    return;
-  }
-
-  console.log(`@mriekki/project-forge\n\nCommands:\n  install   Preview/install bundled Project Forge assets\n  update    Preview/update to this package's bundled Project Forge assets\n  status    Show installed umbrella/component provenance\n  check     Verify managed files and baselines exactly match this package\n  version   Show package version\n\nCommon options:\n  --root PATH\n  --profile greenfield-project\n  --apply | --yes\n  --consumer NAME\n  --consumer-baseline LABEL\n  --accept-retired core:path\n  -h, --help\n`);
-}
-
-export async function run(argv = process.argv.slice(2), packageData = loadPackageData()) {
-  const { command, options } = parseArgs(argv);
-  if (command === 'help') { usage(); return 0; }
-  if (options.help) {
-    if (!['install', 'update', 'status', 'check', 'version'].includes(command)) throw new Error(`Unknown command: ${command}`);
-    usage(command);
-    return 0;
-  }
-  if (command === 'version') { console.log(`${packageData.pkg.name} ${packageData.pkg.version}`); return 0; }
-  const root = path.resolve(options.root ?? process.cwd());
-  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`Repository root not found: ${root}`);
-  const installed = loadProjectForgeBaseline(root);
-  const profile = options.profile ?? installed.profile ?? packageData.assets.defaultProfile;
-
-  if (command === 'status') {
-    if (!Object.keys(installed).length) {
-      console.log(`Project Forge: not installed\nAvailable package: ${packageData.pkg.name}@${packageData.pkg.version}\nProfile: ${profile}`);
-      return 0;
-    }
-    console.log(`Project Forge package: ${installed.package}@${installed.version}`);
-    console.log(`Available package: ${packageData.pkg.name}@${packageData.pkg.version}`);
-    console.log(`Profile: ${installed.profile}`);
-    for (const [name, component] of Object.entries(installed.components ?? {})) {
-      console.log(`${name}: ${component.version ? component.version + ' @ ' : ''}${component.commit}`);
-    }
-    return 0;
-  }
-
-  if (command === 'check') {
-    const result = checkProfile(packageData, profile, root);
-    console.log(`Project Forge package baseline current: ${result.projectForgeCurrent ? 'yes' : 'no'}`);
-    for (const component of result.plan.plans) {
-      const clean = component.metadataCurrent && component.rows.every((row) => row.state === 'SAME') && component.retired.length === 0;
-      console.log(`${component.componentId}: ${clean ? 'PASS' : 'STALE OR DRIFTED'}`);
-    }
-    console.log(`Project Forge check: ${result.clean ? 'PASS' : 'STALE OR DRIFTED'}`);
-    return result.clean ? 0 : 1;
-  }
-
-  if (!['install', 'update'].includes(command)) throw new Error(`Unknown command: ${command}`);
-  if (command === 'install' && Object.keys(installed).length) throw new Error('PROJECT_FORGE_BASELINE.json already exists; use update instead of install');
-  if (command === 'update' && !Object.keys(installed).length) throw new Error('PROJECT_FORGE_BASELINE.json is missing; use install first');
-  if (installed.profile && installed.profile !== profile) throw new Error(`Installed Project Forge profile is ${installed.profile}; refusing implicit profile change to ${profile}`);
-
-  const plan = planProfile(packageData, profile, root, options.acceptedRetired);
-  printPlan(plan);
-  if (plan.unsafe.length) {
-    console.log('\nRefusing apply. Resolve drift/conflicts and preview again. No managed files were changed.');
-    return 2;
-  }
-  const apply = await shouldApply(options);
-  if (!apply) {
-    console.log('\nPreview only. Re-run with --apply, or run interactively and approve the prompt.');
-    return 0;
-  }
-  const baselineConsumers = [...new Set(plan.plans.map((item) => item.baseline.consumer).filter(Boolean))];
-  const baselineLabels = [...new Set(plan.plans.map((item) => item.baseline.consumerBaseline).filter(Boolean))];
-  if (baselineConsumers.length > 1) throw new Error(`Component baselines disagree on consumer identity: ${baselineConsumers.join(', ')}`);
-  if (baselineLabels.length > 1) throw new Error(`Component baselines disagree on consumer baseline: ${baselineLabels.join(', ')}`);
-  const consumer = options.consumer ?? installed.consumer ?? baselineConsumers[0] ?? inferConsumer(root);
-  const consumerBaseline = options.consumerBaseline ?? installed.consumerBaseline ?? baselineLabels[0] ?? `${packageData.pkg.name}@${packageData.pkg.version}`;
-  applyProfile(packageData, plan, root, consumer, consumerBaseline);
-  console.log(`\nProject Forge ${command}: PASS (${packageData.pkg.name}@${packageData.pkg.version})`);
-  return 0;
-}
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { applyProfile, checkProfile, loadProjectForgeBaseline, planProfile } from './engine.mjs';
+import { loadPackageData } from './package-data.mjs';
+
+function parseArgs(argv) {
+  const options = { acceptedRetired: new Map() };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--apply' || arg === '--yes') options.apply = true;
+    else if (arg === '--root') options.root = argv[++i];
+    else if (arg === '--profile') options.profile = argv[++i];
+    else if (arg === '--consumer') options.consumer = argv[++i];
+    else if (arg === '--consumer-baseline') options.consumerBaseline = argv[++i];
+    else if (arg === '--accept-retired') {
+      const value = argv[++i] ?? '';
+      const index = value.indexOf(':');
+      if (index <= 0) throw new Error('--accept-retired must use component:path');
+      const component = value.slice(0, index);
+      const retiredPath = value.slice(index + 1);
+      if (!options.acceptedRetired.has(component)) options.acceptedRetired.set(component, new Set());
+      options.acceptedRetired.get(component).add(retiredPath);
+    } else if (arg.startsWith('-')) throw new Error(`Unknown option: ${arg}`);
+    else positional.push(arg);
+  }
+  return { command: positional[0] ?? 'help', options };
+}
+
+function inferConsumer(root) {
+  try {
+    const origin = execFileSync('git', ['-C', root, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (origin) {
+      const normalized = origin.replace(/\\/g, '/').replace(/\.git$/, '');
+      const match = normalized.match(/[:/]([^/:]+\/[^/]+)$/);
+      if (match) return match[1].split('/').pop();
+    }
+  } catch {}
+  return path.basename(root);
+}
+
+function printPlan(plan) {
+  console.log(`Project Forge profile: ${plan.profileName}`);
+  for (const component of plan.plans) {
+    console.log(`\n${component.componentId.toUpperCase()} ${component.component.commit}`);
+    for (const row of component.rows) console.log(`${row.state.padEnd(20)} ${row.path}`);
+    for (const retired of component.retired) console.log(`${retired.state.padEnd(20)} ${retired.path}`);
+  }
+  console.log(`\nUnsafe drift/conflicts: ${plan.unsafe.length}`);
+  for (const item of plan.unsafe) console.log(`  - ${item.component}: ${item.state}: ${item.path}`);
+}
+
+async function shouldApply(options) {
+  if (options.apply) return true;
+  if (!input.isTTY || !output.isTTY) return false;
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = (await rl.question('Apply this safe Project Forge asset plan? [y/N] ')).trim().toLowerCase();
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+function usage(command) {
+  const commandUsage = {
+    install: 'project-forge install [--root PATH] [--profile NAME] [--apply|--yes] [--consumer NAME] [--consumer-baseline LABEL] [--accept-retired component:path]',
+    update: 'project-forge update [--root PATH] [--profile NAME] [--apply|--yes] [--accept-retired component:path]',
+    status: 'project-forge status [--root PATH] [--profile NAME]',
+    check: 'project-forge check [--root PATH] [--profile NAME]',
+    version: 'project-forge version'
+  };
+
+  if (commandUsage[command]) {
+    console.log(`@mriekki/project-forge\n\nUsage:\n  ${commandUsage[command]}\n`);
+    return;
+  }
+
+  console.log(`@mriekki/project-forge\n\nCommands:\n  install   Preview/install bundled Project Forge assets\n  update    Preview/update to this package's bundled Project Forge assets\n  status    Show installed umbrella/component provenance\n  check     Verify managed files and baselines exactly match this package\n  version   Show package version\n\nCommon options:\n  --root PATH\n  --profile greenfield-project\n  --apply | --yes\n  --consumer NAME\n  --consumer-baseline LABEL\n  --accept-retired core:path\n  -h, --help\n`);
+}
+
+export async function run(argv = process.argv.slice(2), packageData = loadPackageData()) {
+  const { command, options } = parseArgs(argv);
+  if (command === 'help') { usage(); return 0; }
+  if (options.help) {
+    if (!['install', 'update', 'status', 'check', 'version'].includes(command)) throw new Error(`Unknown command: ${command}`);
+    usage(command);
+    return 0;
+  }
+  if (command === 'version') { console.log(`${packageData.pkg.name} ${packageData.pkg.version}`); return 0; }
+  const root = path.resolve(options.root ?? process.cwd());
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`Repository root not found: ${root}`);
+  const installed = loadProjectForgeBaseline(root);
+  const profile = options.profile ?? installed.profile ?? packageData.assets.defaultProfile;
+
+  if (command === 'status') {
+    if (!Object.keys(installed).length) {
+      console.log(`Project Forge: not installed\nAvailable package: ${packageData.pkg.name}@${packageData.pkg.version}\nProfile: ${profile}`);
+      return 0;
+    }
+    console.log(`Project Forge package: ${installed.package}@${installed.version}`);
+    console.log(`Available package: ${packageData.pkg.name}@${packageData.pkg.version}`);
+    console.log(`Profile: ${installed.profile}`);
+    for (const [name, component] of Object.entries(installed.components ?? {})) {
+      console.log(`${name}: ${component.version ? component.version + ' @ ' : ''}${component.commit}`);
+    }
+    return 0;
+  }
+
+  if (command === 'check') {
+    const result = checkProfile(packageData, profile, root);
+    console.log(`Project Forge package baseline current: ${result.projectForgeCurrent ? 'yes' : 'no'}`);
+    for (const component of result.plan.plans) {
+      const clean = component.metadataCurrent && component.rows.every((row) => row.state === 'SAME') && component.retired.length === 0;
+      console.log(`${component.componentId}: ${clean ? 'PASS' : 'STALE OR DRIFTED'}`);
+    }
+    console.log(`Project Forge check: ${result.clean ? 'PASS' : 'STALE OR DRIFTED'}`);
+    return result.clean ? 0 : 1;
+  }
+
+  if (!['install', 'update'].includes(command)) throw new Error(`Unknown command: ${command}`);
+  if (command === 'install' && Object.keys(installed).length) throw new Error('PROJECT_FORGE_BASELINE.json already exists; use update instead of install');
+  if (command === 'update' && !Object.keys(installed).length) throw new Error('PROJECT_FORGE_BASELINE.json is missing; use install first');
+  if (installed.profile && installed.profile !== profile) throw new Error(`Installed Project Forge profile is ${installed.profile}; refusing implicit profile change to ${profile}`);
+
+  const plan = planProfile(packageData, profile, root, options.acceptedRetired);
+  printPlan(plan);
+  if (plan.unsafe.length) {
+    console.log('\nRefusing apply. Resolve drift/conflicts and preview again. No managed files were changed.');
+    return 2;
+  }
+  const apply = await shouldApply(options);
+  if (!apply) {
+    console.log('\nPreview only. Re-run with --apply, or run interactively and approve the prompt.');
+    return 0;
+  }
+  const baselineConsumers = [...new Set(plan.plans.map((item) => item.baseline.consumer).filter(Boolean))];
+  const baselineLabels = [...new Set(plan.plans.map((item) => item.baseline.consumerBaseline).filter(Boolean))];
+  if (baselineConsumers.length > 1) throw new Error(`Component baselines disagree on consumer identity: ${baselineConsumers.join(', ')}`);
+  if (baselineLabels.length > 1) throw new Error(`Component baselines disagree on consumer baseline: ${baselineLabels.join(', ')}`);
+  const consumer = options.consumer ?? installed.consumer ?? baselineConsumers[0] ?? inferConsumer(root);
+  const consumerBaseline = options.consumerBaseline ?? installed.consumerBaseline ?? baselineLabels[0] ?? `${packageData.pkg.name}@${packageData.pkg.version}`;
+  applyProfile(packageData, plan, root, consumer, consumerBaseline);
+  console.log(`\nProject Forge ${command}: PASS (${packageData.pkg.name}@${packageData.pkg.version})`);
+  return 0;
+}