@starci/hfs 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# @starci/hfs
+
+The HFS command line of a StarCi product repository. It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
+and it is self-contained: `runtime/` carries the slot manifest, the canon pins, the Vietnamese why
+catalog slice and the loader, so it runs where there is no runtime checkout.
+
+```sh
+npx hfs check   [--repo <dir>] [--json]       # exit 1 on any error-level finding
+npx hfs init    [--repo <dir>] [--stdout]     # write a starter hfs.json (never overwrites); --stdout only prints
+npx hfs explain <path> [--repo <dir>] [--json]
+npx hfs sync (--check | --write) [--root <dir>]   # generated files: husky, CI, .gitignore block, sonar, codecov (sync/, templates/)
+npx hfs work-hygiene                              # pre-commit guard for staged .starciwork / .starcistacks paths
+```
+
+`hfs check` reads the repository's `hfs.json` and the tracked paths (`git ls-files`), and reports, each with a why code and its
+Vietnamese text (`modules/kernel/failure-codes.yaml`):
+
+| Code | Level | Meaning |
+|---|---|---|
+| `HFS_PATH_NO_SLOT` | error | a tracked path no slot owns (the nearest slot is named) |
+| `HFS_SLOT_NOT_ENABLED` | error | a path in an opt-in slot `hfs.json` did not declare |
+| `HFS_SLOT_AMBIGUOUS` | error | two slots own the path equally (a manifest gap) |
+| `HFS_TRACKED_MUST_BE_IGNORED` | error | a tracked path in an `ignored` slot (build output, generated) |
+| `HFS_FORBIDDEN_PRESENT` | error | a tracked path in a forbidden / `external` slot |
+| `HFS_REQUIRED_MISSING` | error | a file or directory a required slot, app or instance must contain |
+| `HFS_MIN_INSTANCES` | error | fewer instances of a slot than `minInstances` |
+| `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |
+| `HFS_SIZE_SOFT_BACKLOG` | info | a source file over `ruleParams.fileLines.soft`; report only, never fails |
+
+Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag). The command never writes to the repository
+except `hfs init`, which writes `hfs.json` only when none exists.
+
+## Maintaining the bundle
+
+`runtime/` is a byte copy of the runtime files listed in `scripts/sync-runtime.mjs` (plus the catalog slice of the codes the
+check can emit). After changing `scripts/lib/hfs-check.mjs`, `scripts/lib/hfs-slots.mjs`, `knowledge/hfs/slots.yaml`,
+`knowledge/hfs/canon-pins.yaml` or the catalog entries of those codes, run `node packages/hfs/scripts/sync-runtime.mjs`;
+`tests/hfs-cli.spec.mjs` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.

package/bin/hfs.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// hfs - the HFS command line of a StarCi product repository.
+//   hfs check   [--repo <dir>] [--json]     every tracked path has a slot; required files exist; nothing forbidden or
+//                                            tracked-that-must-be-ignored; pins match; soft-size backlog (report only).
+//                                            Exit 1 on any error-level finding.
+//   hfs init    [--repo <dir>] [--stdout]   write a starter hfs.json by detecting the profile and the apps.
+//   hfs explain <path> [--repo <dir>] [--json]   which slot owns the path, its tier, allowed imports, required tests.
+//   hfs sync (--check | --write) [--root <dir>]  the generated files (husky, CI, .gitignore block, sonar, codecov); sync/cli.mjs
+//   hfs work-hygiene                              the pre-commit guard for staged .starciwork and .starcistacks paths; sync/cli.mjs
+// Every finding names a why code and carries its Vietnamese text. The command reads the repository, never writes to it
+// (init writes hfs.json only, and only when none exists). Exit codes: 0 clean, 1 error findings, 2 a refusal or bad usage.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkRepo, explainPath, initRepo } from '../runtime/scripts/lib/hfs-check.mjs';
+import { HfsSlotsError } from '../runtime/scripts/lib/hfs-slots.mjs';
+import { main as syncMain } from '../sync/cli.mjs';
+
+const USAGE = `hfs check [--repo <dir>] [--json]
+hfs init [--repo <dir>] [--stdout]
+hfs explain <path> [--repo <dir>] [--json]
+hfs sync (--check | --write) [--root <dir>]
+hfs work-hygiene
+`;
+const PER_CODE_LIMIT = 25;
+const VALUE_FLAGS = new Set(['--repo']);
+const BOOL_FLAGS = new Set(['--json', '--stdout']);
+
+function parse(argv) {
+  const opts = { positional: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (VALUE_FLAGS.has(arg)) { opts[arg.slice(2)] = argv[i + 1]; i += 1; if (opts[arg.slice(2)] === undefined) throw new Error(`${arg} needs a value`); }
+    else if (BOOL_FLAGS.has(arg)) opts[arg.slice(2)] = true;
+    else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}`);
+    else opts.positional.push(arg);
+  }
+  return opts;
+}
+
+function printCheck(result, out) {
+  const { counts } = result;
+  out(`hfs check ${result.repoRoot} (profile ${result.profile ?? 'unknown'}, manifest ${result.manifest}, ${result.tracked} tracked paths)\n`);
+  const byCode = new Map();
+  for (const f of result.findings) byCode.set(f.code, [...(byCode.get(f.code) ?? []), f]);
+  for (const [code, list] of byCode) {
+    const first = list[0];
+    out(`\n[${first.level.toUpperCase()}] ${code} x${list.length}: ${first.titleVi}\n  ${first.whyVi}\n  -> ${first.nextStepVi}\n`);
+    for (const f of list.slice(0, PER_CODE_LIMIT)) out(`  - ${f.message}\n`);
+    if (list.length > PER_CODE_LIMIT) out(`  ... and ${list.length - PER_CODE_LIMIT} more (use --json for all)\n`);
+  }
+  out(`\n${counts.error} error finding${counts.error === 1 ? '' : 's'}, ${counts.info} report-only\n`);
+}
+
+function printExplain(e, out) {
+  out(`${e.path}\n`);
+  if (e.status === 'no-slot') {
+    out(`  no slot owns this path (${e.code}): ${e.titleVi}\n  ${e.whyVi}\n`);
+    if (e.nearest) out(`  nearest slot ${e.nearest.slot}, pattern ${e.nearest.pattern}; matched ${e.nearest.matchedPrefix || '.'}, then expected ${e.nearest.expectedNext ?? 'nothing'}\n`);
+    return;
+  }
+  if (e.status === 'ambiguous') { out(`  owned equally by ${e.candidates.join(', ')} (${e.code}): ${e.titleVi}\n`); return; }
+  out(`  slot       ${e.slot}  (${e.pattern})\n  presence   ${e.presence}, ${e.tracking}\n  tier       ${e.tier}${e.owner ? `  owner ${e.owner.root} (${e.owner.slot})` : ''}\n`);
+  out(`  imports    ${e.allowedImports ? `may import ${e.allowedImports.join(', ')}; ${e.importRule}` : (e.importRule ?? 'not applicable')}\n`);
+  out(`  tests      ${e.tests}: ${e.testsMeaning}\n`);
+  if (e.requiredFiles.length) out(`  requires   ${e.requiredFiles.join(', ')}\n`);
+  if (e.goesTo) out(`  belongs at ${e.goesTo}\n`);
+  if (e.rules) out(`  rules      ${e.rules.join(', ')}\n`);
+  if (e.code) out(`  ${e.code}: ${e.titleVi}\n  ${e.whyVi}\n`);
+}
+
+export async function main(argv, { stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s) } = {}) {
+  const [verb, ...rest] = argv;
+  if (!['check', 'init', 'explain', 'sync', 'work-hygiene'].includes(verb)) { stderr(USAGE); return 2; }
+  try {
+    if (verb === 'sync' || verb === 'work-hygiene') return await syncMain(argv);
+    const opts = parse(rest);
+    const repoRoot = path.resolve(opts.repo ?? process.cwd());
+    if (verb === 'check') {
+      if (opts.positional.length) throw new Error('hfs check takes no path');
+      const result = checkRepo({ repoRoot });
+      if (opts.json) stdout(`${JSON.stringify(result, null, 2)}\n`); else printCheck(result, stdout);
+      return result.ok ? 0 : 1;
+    }
+    if (verb === 'init') {
+      if (opts.positional.length) throw new Error('hfs init takes no path');
+      const result = initRepo({ repoRoot, write: !opts.stdout });
+      if (opts.stdout) stdout(result.text); else stdout(`hfs init: wrote ${result.file} (${result.declaration.profile}, ${result.declaration.apps.map((a) => `${a.name}:${a.kind}`).join(', ')})\n`);
+      return 0;
+    }
+    if (opts.positional.length !== 1) throw new Error('hfs explain takes exactly one path');
+    const explained = explainPath({ repoRoot, input: opts.positional[0] });
+    if (opts.json) stdout(`${JSON.stringify(explained, null, 2)}\n`); else printExplain(explained, stdout);
+    return explained.status === 'no-slot' || explained.status === 'ambiguous' ? 1 : 0;
+  } catch (error) {
+    stderr(error instanceof HfsSlotsError ? `${error.message}\n` : `hfs: ${error.message}\n${USAGE}`);
+    return 2;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@starci/hfs",
+  "version": "1.0.0",
+  "description": "The HFS command line of a StarCi product repository: hfs check, init, explain, sync and work-hygiene. Self-contained: it carries the runtime files it reads.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "bin": {
+    "hfs": "./bin/hfs.mjs"
+  },
+  "files": [
+    "bin/hfs.mjs",
+    "runtime/**",
+    "sync/**",
+    "templates/**",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync": "node scripts/sync-runtime.mjs",
+    "sync:check": "node scripts/sync-runtime.mjs --check"
+  }
+}

package/runtime/engine/runtime-root.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {parseYaml} from './yaml.mjs';
+
+/**
+ * Runtime root helper. The runtime reads this source tree directly. `skillRoot` is the
+ * directory containing `package.json` (this module's parent) — the checkout, or the copy of it
+ * an install placed on the host.
+ *
+ * Every workflow, op, schema, knowledge and model contract read at runtime is an authored YAML
+ * file (or an authored JSON one where a document is stored that way). `readModuleJson` resolves a
+ * path under `skillRoot` and parses the file by its extension.
+ */
+const moduleRoot = path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)));
+
+/** The runtime root: this source tree (or an immutable sealed payload of it). */
+export const skillRoot = moduleRoot;
+
+/**
+ * Read a runtime contract document. `parts` are path segments under `skillRoot`
+ * (e.g. readModuleJson('modules', 'models', 'kinds.yaml')).
+ */
+export function readModuleJson(...parts) {
+  const rel = parts.join('/');
+  const file = path.join(skillRoot, rel);
+  if (!(file.startsWith(skillRoot) && fs.existsSync(file) && fs.statSync(file).isFile()))
+    throw new Error(`Required contract not found for ${rel} under ${skillRoot}`);
+  const text = fs.readFileSync(file, 'utf8');
+  if (/\.ya?ml$/i.test(file)) return parseYaml(text);
+  return JSON.parse(text);
+}