@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/cli/oa-sync-template.js

@@ -0,0 +1,1020 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `npx oa-sync-template <what> --target <dir>` — writes a generated file of a
+ * bearer from the platform declaration that owns it, or checks that the file on
+ * disk is still what that declaration renders.
+ *
+ * Four runs, one template:
+ *
+ *   * bare paths - the uniform sync of confirmation 001 §3.2. It writes the
+ *     files of the manifest classes `identical` and `generated` from the very
+ *     `from:` reference those rows already point the conformance CHECK at, and
+ *     never touches a file of the `own` class. A row the manifest does not make
+ *     renderable is reported NOT RUN by name, never filled from a guess.
+ *   * `--new <name>` - the whole service tree, from the template that ships
+ *     inside this package (001 §2). It is what `api/scripts/add-service.sh
+ *     --scaffold` runs; that script keeps the platform facts (the registry
+ *     entry, the port), because those are not the shape of a service.
+ *   * `shared-env` - `config/env-templates/shared.env` from
+ *     `api/config/shared-env.json`, the one owner of the shared key set (003 §18).
+ *   * `readme-uniform` - the generated uniform pointer of a README, for a
+ *     library or for a biz service; the kind is read from the target (005).
+ *
+ * There is no flag that points the run at another manifest: the shape has one
+ * owner beside the SSOT (004), and a `--manifest` flag would be a second one
+ * (`.claude/rules/automation-gates.md` §1 requirement 5).
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2, §3.2, §5, §18
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { renderSharedEnv, checkSharedEnv } = require('../sync/sharedEnv');
+const {
+  deriveParams,
+  renderTree,
+  IDENTITY_PARAMS,
+  listTemplateFiles,
+  listOutputFiles,
+  templateIgnores,
+  outputRelative,
+  EXECUTABLE_FILES,
+  ENV_TEMPLATE_SOURCE,
+  envTemplateTarget,
+  PLACEHOLDERS,
+  SSOT_PIN,
+  TEMPLATE_ROOT
+} = require('../sync/serviceTemplate');
+const { planSync, uniformRows } = require('../sync/uniformFiles');
+const { loadManifest: loadUniformManifest, DEFAULT_MANIFEST_PATH } = require('../manifest/loadManifest');
+const {
+  applyUniformRegion,
+  checkUniformRegion,
+  declaredCategory,
+  KINDS
+} = require('../sync/readmePointer');
+const {
+  README_FILE,
+  PACKAGE_ROOT,
+  SERVICE_MANIFEST_IN_PACKAGE,
+  LIBRARY_MANIFEST_IN_PACKAGE,
+  manifestInWorkspace,
+  serviceRegion,
+  libraryRegion
+} = require('../sync/readmeLocation');
+const docsRegion = require('../sync/docsRegion');
+const { resolveWorkspaceRoot, canonicalRoot, WORKSPACE_MARKER } = require('../manifest/workspaceRoot');
+const { loadManifest: loadLibraryManifest, LIBRARY_MANIFEST_PATH } = require('../manifest/loadManifest');
+const { discoverBearers } = require('../manifest/discovery');
+
+/** Exit code for a run that could not start at all — distinct from a finding. */
+const USAGE_EXIT = 2;
+
+/**
+ * The manifest lives beside the SSOT the workspace marker names, so "where is
+ * the workspace" is asked once and answered in one place (004: platform-level
+ * facts live in `api/config/*.json` beside the SSOT).
+ */
+const MANIFEST_RELATIVE = path.join(path.dirname(WORKSPACE_MARKER), 'shared-env.json');
+
+/** Where a bearer keeps the file this subcommand generates. */
+const SHARED_ENV_RELATIVE = path.join('config', 'env-templates', 'shared.env');
+
+/** The same file as a tree key, which is always '/'-separated. */
+const SHARED_ENV_POSIX = 'config/env-templates/shared.env';
+
+/** The platform SSOT of library versions, relative to the workspace root. */
+const LIBRARIES_RELATIVE = path.join(path.dirname(WORKSPACE_MARKER), 'libraries.json');
+
+/** The scope prefix whose versions the SSOT owns. */
+const PINNED_SCOPE = '@onlineapps/';
+
+const USAGE = `
+Usage:
+  oa-sync-template [path...] --target <serviceRoot> [--workspace <root>] [--check]
+  oa-sync-template --new <name> --into <serviceRoot> [--description <text>] [--workspace <root>]
+  oa-sync-template template --target <dir> [--check]
+  oa-sync-template shared-env --target <dir> [--workspace <root>] [--check]
+  oa-sync-template readme-uniform (--target <dir> | --all) [--workspace <root>] [--check]
+  oa-sync-template docs-region (--id <id> | --all) --file <document> [--workspace <root>] [--check]
+  oa-sync-template docs-region --list
+
+  template renders the packaged template into a directory with its own
+  placeholders as the parameters, which is what api/templates/business-service
+  is: generated output, committed for reading (001 §5). --check is the gate.
+
+  With bare paths (or none, meaning all of them) the run rewrites the files the
+  manifest declares in the classes "identical" and "generated", from the same
+  reference the conformance check reads. Files of the "own" class - src/**,
+  tests/**, the content of docs/** - are never written. A row the manifest does
+  not make renderable is printed NOT RUN with the reason.
+
+  --new <name>        create a service tree from the packaged template
+  --into <dir>        where that tree is written; it must not exist yet
+  --description <s>   what the service is for; without it the template's
+                      __SERVICE_DESCRIPTION__ is LEFT standing and the files
+                      carrying it are listed
+
+  Writes <dir>/config/env-templates/shared.env from the platform env manifest
+  api/config/shared-env.json — the one owner of the shared key set. A service
+  adds keys of its own in service.env, never here.
+
+  --target <dir>      the bearer: a service root, api/ itself, or the business
+                      service template
+  --workspace <root>  the directory holding api/ and api_biz/; found upwards
+                      from --target when not given
+  --check             write nothing; exit 1 with a diff when the file on disk is
+                      not what the manifest renders
+
+  readme-uniform writes the generated region of a repository's README.md from
+  the manifest that ships with this package. --target reads the kind from the
+  disk: a root carrying config/service/operations.json is a SERVICE and gets
+  "Uniform: [biz-service](<link>)", the sections of the biz-service manifest and
+  which path falls under which row; a root carrying package.json is a LIBRARY and
+  gets "Uniform: [library/<category>](<link>)" and the duty sections its declared
+  category wears. A library that declares no "oa.category" is reported NOT RUN
+  under --all and never guessed at.
+
+  --all is the library run: the eight service repositories are separate
+  checkouts, not siblings under one workspace, so there is no list to walk - a
+  service is written one --target at a time. A service needs no workspace above
+  it either; its region is the packaged manifest and its link is the copy npm
+  installs into its own node_modules.
+
+  --target <dir>      one library directory or one service root
+  --all               every library the manifest discovers under the workspace
+  --workspace <root>  the directory holding api/ and api_biz/; found upwards
+                      from --target when not given
+  --check             write nothing; exit 1 with a diff when a region on disk is
+                      not what the manifest renders
+
+  docs-region writes the descriptive lists of the documentation tree - the
+  repository shape, the scripts, the runtime numbers, the row table and the
+  library duties - from the two packaged manifests (002 §16.2). It REPLACES a
+  region between markers and never inserts one: those documents belong to other
+  trees, and where a section goes in them is their owner's decision. A document
+  carrying no markers is a failure that prints the two lines to paste.
+
+  --id <id>           one region; --list names them all
+  --all               every region whose markers the document carries
+  --file <document>   the document to write, which its markers name
+  --list              the region ids and what each renders from
+  --check             write nothing; exit 1 with a diff when a region is stale
+
+Exit: 0 written / in sync | 1 drifted or missing under --check | 2 the run could
+not start.
+`;
+
+/**
+ * The named runs. A positional argument is a subcommand ONLY as the first one
+ * and ONLY when it matches this list exactly; every other positional is a
+ * manifest path. Stated rather than inferred, because "it happens not to
+ * collide" is not a rule (`.claude/rules/architecture-principles.md` §8).
+ */
+const SUBCOMMAND_NAMES = Object.freeze(['shared-env', 'readme-uniform', 'template', 'docs-region']);
+
+/** Options that take a directory, and the field each fills. */
+const DIRECTORY_OPTIONS = Object.freeze({
+  '--target': 'target',
+  '--workspace': 'workspace',
+  '--into': 'into'
+});
+
+/** Options that take a value which is not a directory, and the field each fills. */
+const VALUE_OPTIONS = Object.freeze({
+  '--new': 'newName',
+  '--description': 'description',
+  '--id': 'id',
+  '--file': 'file'
+});
+
+/** What a value option is called in its own error message. */
+const VALUE_NAMES = Object.freeze({
+  '--new': 'name',
+  '--description': 'text',
+  '--id': 'region id',
+  '--file': 'document'
+});
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    paths: [],
+    target: null,
+    into: null,
+    workspace: null,
+    newName: null,
+    description: null,
+    id: null,
+    file: null,
+    check: false,
+    all: false,
+    list: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--check') {
+      options.check = true;
+    } else if (arg === '--all') {
+      options.all = true;
+    } else if (arg === '--list') {
+      options.list = true;
+    } else if (DIRECTORY_OPTIONS[arg] !== undefined) {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`[oa-sync-template] ${arg} needs a directory - none followed it. `
+          + `Fix: ${arg} <dir>.`);
+      }
+      options[DIRECTORY_OPTIONS[arg]] = value;
+      index += 1;
+    } else if (VALUE_OPTIONS[arg] !== undefined) {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`[oa-sync-template] ${arg} needs a value - none followed it. `
+          + `Fix: ${arg} <${VALUE_NAMES[arg]}>.`);
+      }
+      options[VALUE_OPTIONS[arg]] = value;
+      index += 1;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`[oa-sync-template] Unknown option "${arg}". Fix: see oa-sync-template with no arguments.`);
+    } else if (options.command === null && options.paths.length === 0 && SUBCOMMAND_NAMES.includes(arg)) {
+      options.command = arg;
+    } else if (options.command !== null) {
+      throw new Error(`[oa-sync-template] Unexpected argument "${arg}" after the subcommand `
+        + `"${options.command}" - a subcommand takes no paths. `
+        + 'Fix: see oa-sync-template with no arguments.');
+    } else {
+      options.paths.push(arg);
+    }
+  }
+
+  return options;
+}
+
+function loadManifest(workspaceRoot) {
+  const manifestPath = path.join(workspaceRoot, MANIFEST_RELATIVE);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`[oa-sync-template] Missing platform env manifest - ${manifestPath} does not exist. `
+      + 'Fix: the shared key set is declared there and nowhere else.');
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`[oa-sync-template] Invalid platform env manifest - ${manifestPath}: ${error.message}`);
+  }
+}
+
+/**
+ * @returns {number} process exit code
+ */
+function runSharedEnv(options) {
+  if (options.target === null) {
+    throw new Error('[oa-sync-template] Missing --target - the run has to be told which bearer to write. '
+      + 'Fix: oa-sync-template shared-env --target <dir>.');
+  }
+
+  const target = path.resolve(options.target);
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace, startDir: target });
+  if (workspaceRoot === null) {
+    throw new Error(`[oa-sync-template] Workspace root not found - no ${WORKSPACE_MARKER} above ${target}. `
+      + 'Fix: pass --workspace <root> pointing at the directory that holds api/ and api_biz/.');
+  }
+
+  const manifest = loadManifest(workspaceRoot);
+  const file = path.join(target, SHARED_ENV_RELATIVE);
+
+  if (options.check) {
+    if (!fs.existsSync(file)) {
+      process.stderr.write(`[oa-sync-template] shared-env is missing - ${file}. `
+        + `Fix: oa-sync-template shared-env --target ${target}\n`);
+      return 1;
+    }
+
+    const result = checkSharedEnv(manifest, fs.readFileSync(file, 'utf8'));
+    if (result.ok) {
+      process.stdout.write(`[oa-sync-template] shared-env is in sync - ${file}\n`);
+      return 0;
+    }
+
+    process.stderr.write(`[oa-sync-template] shared-env drifted from the manifest - ${file}\n`
+      + `${result.diff}\n`
+      + `Fix: oa-sync-template shared-env --target ${target}\n`);
+    return 1;
+  }
+
+  const text = renderSharedEnv(manifest);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  process.stdout.write(`[oa-sync-template] wrote ${manifest.keys.length} keys - ${file}\n`);
+  return 0;
+}
+
+/**
+ * The parsed `package.json` of a directory. A directory without one is not a
+ * library, and the run says so instead of rendering a region for nothing.
+ *
+ * @param {string} dir
+ * @returns {object}
+ */
+function readPackage(dir) {
+  const file = path.join(dir, 'package.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(`[oa-sync-template] Not a package - ${file} does not exist. `
+      + 'Fix: point --target at a library directory that carries package.json.');
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (cause) {
+    throw new Error(`[oa-sync-template] Invalid package.json - ${file}: ${cause.message}`);
+  }
+}
+
+/**
+ * What makes a root a SERVICE: the operations file the platform reads at boot,
+ * which row `C-OPS` of the biz-service manifest owns. A library is what carries
+ * a `package.json` and no such file.
+ *
+ * The kind is read from the disk rather than passed in. A `--kind` flag would be
+ * a second way to say a thing the directory already says, and the two would
+ * eventually disagree (`.claude/rules/automation-gates.md` §1 requirement 5).
+ * The order matters and is stated rather than incidental: a service root carries
+ * a `package.json` too, so the service marker is looked for first.
+ */
+const SERVICE_MARKER = path.join('config', 'service', 'operations.json');
+
+/** What each kind's README is, when the run finds none. */
+const README_FIX = Object.freeze({
+  [KINDS.library]: `Fix: give the package a ${README_FILE} carrying the node header `
+    + '(row L-README of the library manifest).',
+  [KINDS.service]: `Fix: give the service repository a ${README_FILE} - the uniform pointer is a region of it.`
+});
+
+/**
+ * @param {string} dir an absolute root
+ * @returns {string} one of KINDS
+ */
+function detectKind(dir) {
+  if (fs.existsSync(path.join(dir, SERVICE_MARKER))) return KINDS.service;
+  if (fs.existsSync(path.join(dir, 'package.json'))) return KINDS.library;
+  throw new Error(`[oa-sync-template] ${dir} is neither a service nor a package - a service root carries `
+    + 'config/service/operations.json, a library root carries package.json, and this run reads the kind '
+    + 'from the disk rather than being told it. '
+    + 'Fix: point --target at a service repository or a library directory.');
+}
+
+/**
+ * One README, written or checked. Both kinds go through it, so the two runs
+ * cannot drift into two vocabularies of the same result.
+ *
+ * @returns {string|null} the drift report, or null when the file is in sync
+ */
+function syncOneReadme({ dir, label, region, kind, check }) {
+  const file = path.join(dir, README_FILE);
+  if (!fs.existsSync(file)) {
+    throw new Error(`[oa-sync-template] ${label} has no ${README_FILE} - the uniform pointer `
+      + `is a region of that file. ${README_FIX[kind]}`);
+  }
+
+  const text = fs.readFileSync(file, 'utf8');
+
+  if (check) {
+    const result = checkUniformRegion(text, region, { kind });
+    if (result.ok) {
+      process.stdout.write(`[oa-sync-template] readme-uniform is in sync - ${label}/${README_FILE}\n`);
+      return null;
+    }
+    return `[oa-sync-template] readme-uniform drifted from the manifest - `
+      + `${label}/${README_FILE}\n${result.diff}\n`;
+  }
+
+  const applied = applyUniformRegion(text, region, { kind });
+  if (applied === text) {
+    process.stdout.write(`[oa-sync-template] readme-uniform unchanged - ${label}/${README_FILE}\n`);
+  } else {
+    fs.writeFileSync(file, applied);
+    process.stdout.write(`[oa-sync-template] readme-uniform wrote ${label}/${README_FILE}\n`);
+  }
+  return null;
+}
+
+/**
+ * `readme-uniform` - the generated uniform pointer of a library README
+ * (confirmation `biz-service-manifest` 005 point 2).
+ *
+ * A library that declares no category is NOT RUN under `--all`, named on stdout,
+ * and counted out of the coverage line. It is not silently excused and it is not
+ * guessed at: the missing declaration is already the blocking finding
+ * `U-MISMATCH` of `oa-validate --library`, and a second mechanism reporting the
+ * same fact would be a second rail for one concern
+ * (`.claude/rules/change-discipline.md` § One rail per concern;
+ * `.claude/rules/automation-gates.md` §5 - what a run did not cover is said out
+ * loud, never passed over in silence). Asked about that package BY NAME, the run
+ * fails fast instead, because then the answer is the whole result.
+ *
+ * @returns {number} process exit code
+ */
+function runReadmeUniform(options) {
+  if (options.target === null && !options.all) {
+    throw new Error('[oa-sync-template] Missing --target - the run has to be told which library to write, '
+      + 'or --all for every library the manifest discovers. '
+      + 'Fix: oa-sync-template readme-uniform --target <dir>.');
+  }
+  if (options.target !== null && options.all) {
+    throw new Error('[oa-sync-template] --target and --all are exclusive - a run writes one library or '
+      + 'every library, never both. Fix: drop one of them.');
+  }
+
+  // The target is canonicalised once, here: the region's link is
+  // `path.relative(target, manifestPath)` and the manifest path is derived from
+  // the workspace root, which resolves through its symlinks. Two spellings of
+  // one directory made that link climb out of the workspace and back in
+  // (`workspaceRoot.js` § canonicalRoot).
+  const target = options.all ? null : canonicalRoot(options.target);
+
+  if (!options.all && detectKind(target) === KINDS.service) {
+    return runServiceReadme(target, options);
+  }
+  return runLibraryReadme({ ...options, target });
+}
+
+/**
+ * `readme-uniform --target <service>` - the uniform pointer of a biz service.
+ *
+ * The link points at the manifest as it lies in the service AFTER `npm install`:
+ * `node_modules/@onlineapps/conn-orch-validator/manifests/biz-service.manifest.json`,
+ * the copy the pin decides and the one `oa-validate` reads there. It is derived
+ * from this package's own name and the manifest's position inside it, never
+ * typed, and it is deliberately a path rather than a URL - a reader of the
+ * repository resolves it without a network.
+ *
+ * No workspace is resolved and none is required: a service repository is its own
+ * checkout, and the region's whole content is the packaged manifest. The
+ * workspace is consulted for one thing only - what to call the target on stdout -
+ * and its absence is not an error.
+ *
+ * @returns {number} process exit code
+ */
+function runServiceReadme(target, options) {
+  const region = serviceRegion(target);
+
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace, startDir: target });
+  const label = workspaceRoot === null
+    ? target
+    : path.relative(workspaceRoot, target).split(path.sep).join('/');
+
+  const drift = syncOneReadme({
+    dir: target, label, region, kind: KINDS.service, check: options.check
+  });
+
+  if (drift !== null) {
+    process.stderr.write(`${drift}Fix: npx oa-sync-template readme-uniform --target ${target}\n`);
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * `readme-uniform` over the libraries of one workspace - one named by `--target`,
+ * or every one the manifest's discovery block finds under `--all`.
+ *
+ * @returns {number} process exit code
+ */
+function runLibraryReadme(options) {
+  const target = options.target;
+  const workspaceRoot = resolveWorkspaceRoot({
+    explicit: options.workspace,
+    startDir: target === null ? PACKAGE_ROOT : target
+  });
+  if (workspaceRoot === null) {
+    throw new Error(`[oa-sync-template] Workspace root not found - no ${WORKSPACE_MARKER} above `
+      + `${target === null ? PACKAGE_ROOT : target}. `
+      + 'Fix: pass --workspace <root> pointing at the directory that holds api/ and api_biz/.');
+  }
+
+  const manifest = loadLibraryManifest(LIBRARY_MANIFEST_PATH);
+  const block = manifest.discovery && manifest.discovery.library;
+  if (!block) {
+    throw new Error('[oa-sync-template] Library manifest declares no discovery.library block - the run finds '
+      + 'the libraries from it and knows no list of its own. '
+      + `Fix: repair ${LIBRARY_MANIFEST_PATH}.`);
+  }
+
+  const { bearers } = discoverBearers({ block, workspaceRoot });
+
+  const relativeOf = (dir) => path.relative(workspaceRoot, dir).split(path.sep).join('/');
+  const packages = options.all
+    ? bearers.map((bearer) => ({ dir: bearer.dir, relativeDir: bearer.relativeDir }))
+    : [{ dir: target, relativeDir: relativeOf(target) }];
+
+  const drifted = [];
+  let covered = 0;
+  let notRun = 0;
+
+  for (const entry of packages) {
+    const pkg = readPackage(entry.dir);
+
+    if (declaredCategory(pkg) === null) {
+      if (!options.all) {
+        throw new Error(`[oa-sync-template] ${entry.relativeDir} declares no "oa"."category" - the layer a `
+          + 'package is meant to sit in cannot be derived from anything else, so the pointer cannot be '
+          + 'rendered. Fix: declare "oa": { "category": "<core|connector|orchestration|runtime|tooling>" } '
+          + 'in package.json.');
+      }
+      process.stdout.write(`[oa-sync-template] readme-uniform NOT RUN - ${entry.relativeDir} declares no `
+        + '"oa"."category"; that is finding U-MISMATCH of oa-validate --library, and this run never '
+        + 'guesses one\n');
+      notRun += 1;
+      continue;
+    }
+
+    const region = libraryRegion({ packageDir: entry.dir, pkg, workspaceRoot, manifest });
+    covered += 1;
+
+    const drift = syncOneReadme({
+      dir: entry.dir,
+      label: entry.relativeDir,
+      region,
+      kind: KINDS.library,
+      check: options.check
+    });
+    if (drift !== null) drifted.push(drift);
+  }
+
+  if (options.all) {
+    process.stdout.write(`[oa-sync-template] readme-uniform covered ${covered} of ${covered + notRun} libraries\n`);
+  }
+
+  if (drifted.length > 0) {
+    const fix = options.all ? '--all' : `--target ${target}`;
+    process.stderr.write(`${drifted.join('')}Fix: npx oa-sync-template readme-uniform ${fix}\n`);
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * `docs-region` - a generated region of the documentation tree, rendered from
+ * the two packaged manifests (confirmation `biz-service-manifest` 002 §16.2).
+ *
+ * The run REPLACES a region and never inserts one. The documents live in
+ * `api/docs/**`, a tree owned by other threads: deciding on their behalf where a
+ * section belongs would be the unsafe side effect `automation-gates.md` §1
+ * requirement 3 forbids, and a marker nobody put there is a section nobody
+ * agreed to. So a document with no markers is a failure that prints the two
+ * lines to paste, and `--all` covers exactly the regions a document already
+ * declares.
+ *
+ * @returns {number} process exit code
+ */
+function runDocsRegion(options) {
+  if (options.list) {
+    process.stdout.write('[oa-sync-template] docs-region renders, from the manifests this package ships:\n');
+    for (const id of docsRegion.REGION_IDS) {
+      process.stdout.write(`  ${id} - ${docsRegion.describeRegion(id)}\n`);
+    }
+    return 0;
+  }
+
+  if (options.file === null) {
+    throw new Error('[oa-sync-template] Missing --file - the run has to be told which document to write, '
+      + 'and the region carries that path in its own marker. '
+      + 'Fix: oa-sync-template docs-region --id <id> --file <document>, or --list to see the ids.');
+  }
+  if (options.id === null && !options.all) {
+    throw new Error('[oa-sync-template] Missing --id - the run writes one named region, or --all for every '
+      + 'region the document already declares. '
+      + 'Fix: oa-sync-template docs-region --id <id> --file <document>, or --list to see the ids.');
+  }
+  if (options.id !== null && options.all) {
+    throw new Error('[oa-sync-template] --id and --all are exclusive - a run writes one region or every '
+      + 'region the document declares, never both. Fix: drop one of them.');
+  }
+
+  const given = path.resolve(options.file);
+  if (!fs.existsSync(given)) {
+    throw new Error(`[oa-sync-template] Document does not exist - ${given}. `
+      + 'Fix: point --file at the document that carries the markers.');
+  }
+  // The document's own directory is canonicalised, so the label — and with it
+  // the marker the region is found by — is relative to the workspace root in
+  // the same spelling (`workspaceRoot.js` § canonicalRoot).
+  const file = path.join(canonicalRoot(path.dirname(given)), path.basename(given));
+
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace, startDir: path.dirname(file) });
+  if (workspaceRoot === null) {
+    throw new Error(`[oa-sync-template] Workspace root not found - no ${WORKSPACE_MARKER} above ${file}. `
+      + 'Fix: pass --workspace <root> pointing at the directory that holds api/ and api_biz/.');
+  }
+
+  const targetLabel = path.relative(workspaceRoot, file).split(path.sep).join('/');
+  const serviceManifest = loadUniformManifest(DEFAULT_MANIFEST_PATH);
+  const libraryManifest = loadLibraryManifest(LIBRARY_MANIFEST_PATH);
+
+  const block = libraryManifest.discovery && libraryManifest.discovery.library;
+  if (!block) {
+    throw new Error('[oa-sync-template] Library manifest declares no discovery.library block - the run finds '
+      + 'this package through it to compute the link the region carries. '
+      + `Fix: repair ${LIBRARY_MANIFEST_PATH}.`);
+  }
+  const { bearers } = discoverBearers({ block, workspaceRoot });
+  const render = {
+    serviceManifest,
+    libraryManifest,
+    serviceManifestPath: manifestInWorkspace({
+      workspaceRoot, relativeInPackage: SERVICE_MANIFEST_IN_PACKAGE
+    }),
+    libraryManifestPath: manifestInWorkspace({
+      workspaceRoot, relativeInPackage: LIBRARY_MANIFEST_IN_PACKAGE
+    }),
+    targetPath: file,
+    targetLabel,
+    templateFiles: listTemplateFiles(TEMPLATE_ROOT).map(outputRelative)
+  };
+
+  let text = fs.readFileSync(file, 'utf8');
+  const ids = options.all ? docsRegion.regionIdsIn(text, targetLabel) : [options.id];
+
+  if (ids.length === 0) {
+    throw new Error(`[oa-sync-template] ${targetLabel} carries no generated region of this run - docs-region `
+      + 'replaces a region and never decides where one belongs in a document it does not own. '
+      + `Fix: put the markers of one of ${docsRegion.REGION_IDS.join(', ')} where the region belongs `
+      + '(oa-sync-template docs-region --list names what each renders), then run this again.');
+  }
+
+  const drifted = [];
+  let changed = false;
+
+  for (const id of ids) {
+    const region = docsRegion.renderRegion(id, render);
+
+    if (options.check) {
+      const result = docsRegion.checkRegion(text, id, region, { targetLabel });
+      if (result.ok) {
+        process.stdout.write(`[oa-sync-template] docs-region is in sync - ${targetLabel} (${id})\n`);
+      } else {
+        drifted.push(`[oa-sync-template] docs-region drifted from the manifest - ${targetLabel} (${id})\n`
+          + `${result.diff}\n`);
+      }
+      continue;
+    }
+
+    const applied = docsRegion.applyRegion(text, id, region, { targetLabel });
+    if (applied === text) {
+      process.stdout.write(`[oa-sync-template] docs-region unchanged - ${targetLabel} (${id})\n`);
+    } else {
+      text = applied;
+      changed = true;
+      process.stdout.write(`[oa-sync-template] docs-region wrote ${id} - ${targetLabel}\n`);
+    }
+  }
+
+  if (changed) fs.writeFileSync(file, text);
+
+  if (drifted.length > 0) {
+    process.stderr.write(`${drifted.join('')}Fix: npx oa-sync-template docs-region `
+      + `${options.all ? '--all' : `--id ${options.id}`} --file ${targetLabel}\n`);
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Where the workspace root is, for a run that was given a service root.
+ *
+ * @param {{explicit: string|null, startDir: string}} params
+ * @returns {string}
+ */
+function requireWorkspaceRoot({ explicit, startDir }) {
+  const workspaceRoot = resolveWorkspaceRoot({ explicit, startDir });
+  if (workspaceRoot === null) {
+    throw new Error(`[oa-sync-template] Workspace root not found - no ${WORKSPACE_MARKER} above ${startDir}. `
+      + 'Fix: pass --workspace <root> pointing at the directory that holds api/ and api_biz/.');
+  }
+  return workspaceRoot;
+}
+
+/**
+ * Write one file of a service tree, creating the directories it needs.
+ *
+ * `init.sh` is the one file written executable: it is the container entrypoint,
+ * and a template file cannot carry the bit through `npm pack`
+ * (`EXECUTABLE_FILES` is where that fact lives).
+ */
+function writeServiceFile(serviceRoot, relative, text) {
+  const file = path.join(serviceRoot, ...relative.split('/'));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  if (EXECUTABLE_FILES.includes(relative)) fs.chmodSync(file, 0o755);
+}
+
+/**
+ * `oa-sync-template [path...]` - the uniform sync (confirmation 001 §3.2).
+ *
+ * @returns {number} process exit code
+ */
+function runSync(options) {
+  // The positionals are judged FIRST, against the manifest, and before anything
+  // that touches the disk: a mistyped subcommand must be named as what it is,
+  // not reported as a missing workspace three steps later.
+  const declared = uniformRows(loadUniformManifest(DEFAULT_MANIFEST_PATH)).map((row) => row.path);
+  for (const wanted of options.paths) {
+    if (declared.includes(wanted)) continue;
+    throw new Error(`[oa-sync-template] Unknown argument "${wanted}" - it is neither a subcommand this run `
+      + `has (${SUBCOMMAND_NAMES.join(', ')}) nor a path the uniform declares (${declared.join(', ')}). `
+      + 'Fix: name one of those, or leave the paths out to write them all.');
+  }
+
+  if (options.target === null) {
+    throw new Error('[oa-sync-template] Missing --target - the run has to be told which service to write. '
+      + 'Fix: oa-sync-template [path...] --target <serviceRoot>.');
+  }
+
+  const target = path.resolve(options.target);
+  const manifest = loadUniformManifest(DEFAULT_MANIFEST_PATH);
+
+  // A workspace is not a precondition of this run, it is a precondition of the
+  // ROWS that read a workspace file — and since d.229 most of them read a file
+  // this package carries instead. Demanding one up front made the `fix` command
+  // of F-INIT, F-JEST and F-RUNNER unrunnable in the one place their finding is
+  // now raised: inside the service image. A row that does need it is reported
+  // NOT RUN by name, never silently skipped (`automation-gates.md` §5).
+  const workspaceRoot = resolveWorkspaceRoot({ explicit: options.workspace, startDir: target });
+  const entries = planSync({ manifest, serviceRoot: target, workspaceRoot, paths: options.paths });
+
+  let changed = 0;
+  let blocked = 0;
+
+  for (const entry of entries) {
+    const where = `${entry.id} ${entry.path}`;
+    if (entry.outcome === 'not-run') {
+      process.stdout.write(`[oa-sync-template] NOT RUN ${where} - ${entry.reason}\n`);
+    } else if (entry.outcome === 'blocked') {
+      blocked += 1;
+      process.stderr.write(`[oa-sync-template] BLOCKED ${where} - ${entry.reason}\n`);
+    } else if (entry.outcome === 'unchanged') {
+      process.stdout.write(`[oa-sync-template] unchanged ${where}\n`);
+    } else if (options.check) {
+      changed += 1;
+      process.stdout.write(`[oa-sync-template] would change ${where} - ${entry.detail}\n`);
+    } else {
+      changed += 1;
+      writeServiceFile(target, entry.path, entry.desired);
+      process.stdout.write(`[oa-sync-template] wrote ${where} - ${entry.detail}\n`);
+    }
+  }
+
+  if (options.check && changed > 0) {
+    process.stderr.write(`[oa-sync-template] ${changed} file(s) would change - ${target}\n`
+      + `Fix: npx oa-sync-template --target ${target}\n`);
+  }
+  return changed > 0 && options.check ? 1 : (blocked > 0 ? 1 : 0);
+}
+
+/**
+ * The platform SSOT of library versions.
+ *
+ * @param {string} workspaceRoot
+ * @returns {object} the parsed `libraries` map
+ */
+function loadLibraries(workspaceRoot) {
+  const file = path.join(workspaceRoot, LIBRARIES_RELATIVE);
+  if (!fs.existsSync(file)) {
+    throw new Error(`[oa-sync-template] Missing library SSOT - ${file} does not exist. `
+      + 'Fix: a new service pins every @onlineapps dependency to the platform SSOT, which is that file.');
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (cause) {
+    throw new Error(`[oa-sync-template] Invalid library SSOT - ${file}: ${cause.message}`);
+  }
+  if (parsed === null || typeof parsed.libraries !== 'object' || parsed.libraries === null) {
+    throw new Error(`[oa-sync-template] Library SSOT declares no "libraries" map - ${file}. `
+      + 'Fix: the pins are read from that key and from nowhere else.');
+  }
+  return parsed.libraries;
+}
+
+/**
+ * The service's `package.json` with every `@onlineapps/*` pin taken from the
+ * platform SSOT rather than from whatever version the template was last touched
+ * with (`.claude/rules/architecture-principles.md` § Version pinning).
+ *
+ * The template does not state a version at all: it writes `SSOT_PIN`, and this
+ * is the one place that resolves it. A dependency the SSOT does not know FAILS
+ * the run - guessing a version, or leaving the template's, is how a service ends
+ * up installing code the platform never proved.
+ *
+ * The pass ends by refusing a placeholder it did not resolve, which can only be
+ * one written OUTSIDE the platform scope: no SSOT owns that name, so nothing
+ * here can fill it in, and the alternative to stopping is a `package.json`
+ * carrying a version npm cannot parse - discovered at the first `npm ci` rather
+ * than at the run that wrote it (`.claude/rules/architecture-principles.md` §4).
+ *
+ * @param {string} text rendered package.json
+ * @param {object} libraries the SSOT map
+ * @returns {string}
+ */
+function pinLibraries(text, libraries) {
+  const pkg = JSON.parse(text);
+  for (const field of ['dependencies', 'devDependencies']) {
+    const block = pkg[field];
+    if (block === undefined) continue;
+    for (const name of Object.keys(block)) {
+      if (!name.startsWith(PINNED_SCOPE)) continue;
+      const version = libraries[name];
+      if (typeof version !== 'string') {
+        throw new Error(`[oa-sync-template] Missing library version - "${name}" has no entry in `
+          + `${LIBRARIES_RELATIVE}. Fix: add it to the platform SSOT, or drop the dependency from the `
+          + 'business-service template.');
+      }
+      block[name] = version;
+    }
+  }
+
+  for (const field of ['dependencies', 'devDependencies']) {
+    const block = pkg[field];
+    if (block === undefined) continue;
+    for (const [name, version] of Object.entries(block)) {
+      if (typeof version === 'string' && version.includes(SSOT_PIN)) {
+        throw new Error(`[oa-sync-template] Unresolved ${SSOT_PIN} - "${name}" asks for a platform pin, `
+          + `but ${LIBRARIES_RELATIVE} owns the versions of ${PINNED_SCOPE}* and of nothing else, so `
+          + 'nothing can fill it in. Fix: give that dependency its exact version in the business-service '
+          + `template, or move it under ${PINNED_SCOPE}.`);
+      }
+    }
+  }
+  return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+
+/**
+ * `oa-sync-template --new <name> --into <dir>` - a whole service tree
+ * (confirmation 001 §3.2, and §5: this is what `api/templates/business-service`
+ * is the output of).
+ *
+ * Three things happen to the rendered tree, and each is here because it is a
+ * fact about ONE service rather than about the shape:
+ *   * the env template is named after the service, the way every live repo has it;
+ *   * `shared.env` comes from the platform env manifest, its one owner (003 §18);
+ *   * every `@onlineapps` pin comes from the platform SSOT.
+ *
+ * @returns {number} process exit code
+ */
+function runNew(options) {
+  if (options.into === null) {
+    throw new Error('[oa-sync-template] Missing --into - the run has to be told where the service tree goes. '
+      + 'Fix: oa-sync-template --new <name> --into <serviceRoot>.');
+  }
+  if (options.command !== null || options.paths.length > 0 || options.all || options.check) {
+    throw new Error('[oa-sync-template] --new creates a service and takes no subcommand, path, --all or '
+      + '--check - there is nothing on disk yet to compare against. Fix: run --new on its own.');
+  }
+
+  const params = deriveParams({ name: options.newName, description: options.description });
+  const into = path.resolve(options.into);
+  if (fs.existsSync(into)) {
+    throw new Error(`[oa-sync-template] ${into} already exists - a service tree is written into a directory `
+      + 'that does not exist yet, so nothing anybody else wrote is overwritten. '
+      + 'Fix: remove it, or pass --into <another directory>.');
+  }
+
+  const workspaceRoot = requireWorkspaceRoot({ explicit: options.workspace, startDir: path.dirname(into) });
+  const envManifest = loadManifest(workspaceRoot);
+  const libraries = loadLibraries(workspaceRoot);
+
+  const tree = renderTree({ params });
+
+  const envTemplate = tree.get(ENV_TEMPLATE_SOURCE);
+  tree.delete(ENV_TEMPLATE_SOURCE);
+  tree.set(envTemplateTarget(params.service_name), envTemplate);
+
+  tree.set(SHARED_ENV_POSIX, renderSharedEnv(envManifest));
+  tree.set('package.json', pinLibraries(tree.get('package.json'), libraries));
+
+  for (const [relative, text] of tree) writeServiceFile(into, relative, text);
+
+  process.stdout.write(`[oa-sync-template] --new wrote ${tree.size} files - ${into}\n`);
+
+  if (params.description === null) {
+    const pending = [...tree.entries()]
+      .filter(([, text]) => text.includes(PLACEHOLDERS.description))
+      .map(([relative]) => relative);
+    process.stdout.write(`[oa-sync-template] ${PLACEHOLDERS.description} is still in place - this run was `
+      + `given no description. Files carrying it: ${pending.join(', ')}\n`);
+  }
+  return 0;
+}
+
+/**
+ * `oa-sync-template template --target <dir>` - the template as GENERATED OUTPUT
+ * (confirmation `biz-service-manifest` 001 §5).
+ *
+ * `api/templates/business-service` stopped being hand-maintained the day the
+ * template moved into this package. What it is now is this run's output: the
+ * renderer with `IDENTITY_PARAMS`, which substitutes every placeholder by
+ * itself. That is what makes §9's acceptance measurable instead of felt - the
+ * directory differs from the generator's output by nothing, and `--check` says
+ * so with an exit code.
+ *
+ * It takes no workspace and no parameters: there is no service here to name.
+ *
+ * @returns {number} process exit code
+ */
+function runTemplate(options) {
+  if (options.target === null) {
+    throw new Error('[oa-sync-template] Missing --target - the run has to be told where the rendered '
+      + 'template goes. Fix: oa-sync-template template --target api/templates/business-service.');
+  }
+
+  const target = path.resolve(options.target);
+  const tree = renderTree({ params: IDENTITY_PARAMS });
+  const drifted = [];
+  let written = 0;
+
+  // The template's own `.gitignore` says which paths of a rendered tree are
+  // generated output, and this comparison reads that rule on BOTH sides: a
+  // source file under such a path would be a file no service could ever commit,
+  // and a target file under one is the artefact of a legitimate run. `oa-validate`
+  // records its verdict in the tree it measured (d.232), so a run over the
+  // mirror leaves `ci/deployability.json` there — git does not see it, and
+  // neither does this check (d.237).
+  const ignored = templateIgnores();
+
+  for (const [relative, text] of tree) {
+    if (ignored(relative)) continue;
+    const file = path.join(target, ...relative.split('/'));
+    const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+
+    if (current === text) continue;
+    if (options.check) {
+      drifted.push(`[oa-sync-template] template would change ${relative} - `
+        + `${current === null ? 'absent' : 'differs from the packaged template'}\n`);
+      continue;
+    }
+    writeServiceFile(target, relative, text);
+    written += 1;
+  }
+
+  const surplus = fs.existsSync(target)
+    ? listOutputFiles(target).filter((relative) => !tree.has(relative))
+    : [];
+  for (const relative of surplus) {
+    drifted.push(`[oa-sync-template] template carries ${relative}, which the packaged template does not - `
+      + 'the directory is output, so a file with no source in it is stale\n');
+  }
+
+  if (drifted.length > 0) {
+    process.stderr.write(`${drifted.join('')}Fix: npx oa-sync-template template --target ${target}\n`);
+    return 1;
+  }
+  process.stdout.write(`[oa-sync-template] template ${options.check ? 'is in sync' : `wrote ${written} of ${tree.size} files`} - ${target}\n`);
+  return 0;
+}
+
+const SUBCOMMANDS = Object.freeze({
+  'shared-env': runSharedEnv,
+  'readme-uniform': runReadmeUniform,
+  'docs-region': runDocsRegion,
+  template: runTemplate
+});
+
+/**
+ * @param {string[]} argv arguments after the executable and script
+ * @returns {number} process exit code
+ */
+function main(argv) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return USAGE_EXIT;
+  }
+
+  const run = options.newName !== null
+    ? runNew
+    : (options.command !== null ? SUBCOMMANDS[options.command] : null);
+
+  if (run === null && options.paths.length === 0 && options.target === null) {
+    process.stderr.write(`${USAGE}`);
+    return USAGE_EXIT;
+  }
+
+  try {
+    return (run === null ? runSync : run)(options);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return USAGE_EXIT;
+  }
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}
+
+module.exports = { main, parseArgs, USAGE_EXIT, MANIFEST_RELATIVE, SHARED_ENV_RELATIVE, README_FILE };