@starci/eslint-canon-fe 9.13.1 → 9.13.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 9.13.3 - 2026-11-04
+
+- Changed: the runtime copies carry `engine/runtime-root.mjs`, which moves an installed copy's legacy state with its owner and mode (`@starci/hfs` 5.6.1), and the release-5 canon pins.
+
+## 9.13.2 - 2026-11-04
+
+- Changed: the runtime copies carry `engine/runtime-root.mjs` with the per-user state base of an installed copy (`@starci/hfs` 5.6.0) and the canon pins of release 4 (`@starci/auth` 0.4.0, `@starci/auth-oidc` 0.1.3).
+
 ## 9.13.1 - 2026-11-04
 
 - Changed: the runtime copy of the canon pins names the release-3 versions (`@starci/hfs` 5.5.1, `@starci/jest-preset` 2.7.1, `@starci/eslint-canon-be` 3.15.1, the Grammar family 0.21.18).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "9.13.1",
+  "version": "9.13.3",
   "description": "Universal front-end lint laws for TypeScript and Next.js, independent of the selected Grammar family.",
   "type": "module",
   "license": "MIT",

package/runtime/engine/runtime-root.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from './yaml.mjs';
@@ -24,17 +25,102 @@ export const LOCAL_ROOT_ENV = 'STARCI_LOCAL_ROOT';
 /** The host-data directory of a runtime root. Git-ignored and never packed; the example fixtures under examples/.runtimes are a separate, public exception. */
 export const RUNTIME_STATE_DIR = '.runtime';
 /**
- * <root>/.runtime. The root is the `.claude` of the host Source: the checkout, or the copy `starci runtime install` places at
- * <app>/.claude. ~/.starci/runtime/node_modules/starci is only the CLI's download cache (it supplies the installer and hosts no
- * state), and `starci runtime link` merely points the launcher at a root, so the state follows the code's own location.
+ * <root>/.runtime, the state base of a runtime root that is a checkout (the harness repository, or a copy of it placed on the host).
+ * An installed or locally sourced copy keeps none (see installedStateBase).
  */
 export const runtimeStateDir = (root = skillRoot) => path.join(root, RUNTIME_STATE_DIR);
+/** True when `root` is a copy an install or `starci deps source --local` placed below a node_modules folder, not a checkout. */
+export const installedRoot = (root = skillRoot) => path.resolve(root).split(/[\\/]/).includes('node_modules');
+/**
+ * The per-user state base of an installed copy: LOCALAPPDATA (Windows), else XDG_STATE_HOME, else ~/.local/state, then
+ * starci-harness/state. It lies outside every package and every product repository, so `npm ci` and a package copy never delete a
+ * running stack's data, and every installed copy on the host shares one machine.sqlite and one stack/<project>/<env> per environment.
+ */
+export const installedStateBase = (env = process.env) => path.join(env['LOCALAPPDATA'] || env['XDG_STATE_HOME'] || path.join(os.homedir(), '.local', 'state'), 'starci-harness', 'state');
 /**
  * The per-host state base, the one owner of every host-state location: machine.sqlite, projects/<ledger_id>/runtime.sqlite, archive/,
- * artifacts/ (the blob store), guards/, host-lock/ and the other process state sit under it. Default <runtime root>/.runtime;
- * LOCAL_ROOT_ENV replaces it wholesale. Nothing is read from or moved out of the earlier %LOCALAPPDATA%/StarCi and ~/.starci locations.
+ * artifacts/ (the blob store), guards/, host-lock/, stack/<project>/<env>/ and the other process state sit under it. LOCAL_ROOT_ENV
+ * replaces it wholesale; else a checkout keeps it in <runtime root>/.runtime and an installed copy in installedStateBase.
+ */
+export const starciLocalRoot = (env = process.env, root = skillRoot) => {
+    if (env[LOCAL_ROOT_ENV])
+        return path.resolve(env[LOCAL_ROOT_ENV]);
+    return installedRoot(root) ? installedStateBase(env) : runtimeStateDir(root);
+};
+/** The refusal of a legacy state base a running process still holds (a stack's bind mounts, an open log). */
+export class LegacyStateHeld extends Error {
+    code = 'HFS_STATE_LEGACY_HELD';
+    legacy;
+    constructor(legacy, cause) {
+        super(`${legacy} holds the state of a running stack and cannot move out of the package yet; run \`starci app stack down --env <env>\` for each running environment, then any \`starci app\` verb moves it`, { cause });
+        this.legacy = legacy;
+    }
+}
+const HELD = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const isHeld = (error) => HELD.has(String(error?.code));
+/** Gives `to` and everything below it the mode, owner and group of the matching entry of `from` (a copy keeps neither on its own). */
+function keepOwnership(from, to) {
+    const source = fs.lstatSync(from);
+    const target = fs.lstatSync(to);
+    if (!source.isSymbolicLink())
+        fs.chmodSync(to, source.mode & 0o7777);
+    if (source.uid !== target.uid || source.gid !== target.gid)
+        fs.lchownSync(to, source.uid, source.gid);
+    if (source.isDirectory())
+        for (const name of fs.readdirSync(from))
+            keepOwnership(path.join(from, name), path.join(to, name));
+}
+/** Moves one entry by rename, which keeps its owner and mode; across volumes (EXDEV) it is copied, its ownership restored, then removed. */
+function moveEntry(from, to) {
+    try {
+        fs.renameSync(from, to);
+        return;
+    }
+    catch (error) {
+        if (error?.code !== 'EXDEV')
+            throw error;
+    }
+    fs.cpSync(from, to, { recursive: true, verbatimSymlinks: true, errorOnExist: true, force: false });
+    keepOwnership(from, to);
+    fs.rmSync(from, { recursive: true, force: true });
+}
+/**
+ * Moves the state an installed copy kept inside itself (<copy>/.runtime, before installedStateBase) out to the state base, once: the
+ * folder is first renamed to <copy>/.runtime.adopting (a rename a running stack's open files refuse, LegacyStateHeld), then each entry
+ * is moved with its owner and mode (a bind folder a container user owns stays that user's) and the folder removed. An entry the state base already holds is kept beside it under legacy-<stamp>/, never overwritten. An
+ * interrupted adoption resumes from .runtime.adopting. Null when there is nothing to adopt: a checkout, LOCAL_ROOT_ENV set, or no
+ * legacy folder.
  */
-export const starciLocalRoot = (env = process.env, root = skillRoot) => (env[LOCAL_ROOT_ENV] ? path.resolve(env[LOCAL_ROOT_ENV]) : runtimeStateDir(root));
+export function adoptLegacyState(env = process.env, root = skillRoot, now = () => new Date()) {
+    if (env[LOCAL_ROOT_ENV] || !installedRoot(root))
+        return null;
+    const from = runtimeStateDir(root);
+    const parked = `${from}.adopting`;
+    if (!fs.existsSync(parked)) {
+        if (!fs.existsSync(from))
+            return null;
+        try {
+            fs.renameSync(from, parked);
+        }
+        catch (error) {
+            if (isHeld(error))
+                throw new LegacyStateHeld(from, error);
+            throw error;
+        }
+    }
+    const to = installedStateBase(env);
+    const aside = path.join(to, `legacy-${now().toISOString().replace(/[^0-9]/g, '').slice(0, 14)}`);
+    const moved = [];
+    const kept = [];
+    for (const name of fs.readdirSync(parked).sort()) {
+        const taken = fs.existsSync(path.join(to, name));
+        fs.mkdirSync(taken ? aside : to, { recursive: true });
+        moveEntry(path.join(parked, name), path.join(taken ? aside : to, name));
+        (taken ? kept : moved).push(name);
+    }
+    fs.rmSync(parked, { recursive: true, force: true });
+    return { from, to, moved, kept };
+}
 /**
  * Read a runtime contract document. `parts` are path segments under `skillRoot`
  * (e.g. readModuleJson('modules', 'models', 'kinds.yaml')).

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -38,7 +38,7 @@ pins:
     source: packages/next-data/package.json
     why: 'the SWR data helpers of every front end (fe-stack data, owner:next-data-package): pollingRestart, the viewer and tenant key helpers, viewerSwrConfig and the viewer cache; each operation hook stays in the app and the package holds no component.'
   '@starci/grammar':
-    version: 0.21.18
+    version: 0.21.20
     group: starci
     install: registry
     side: fe
@@ -52,28 +52,28 @@ pins:
     source: packages/next-i18n/package.json
     why: 'the next-intl stack of every front end (fe-stack i18n, owner:next-i18n-package): defineI18n over the locales of the app, the locale-negotiating proxy, the locale-aware navigation, the request config that loads the catalogs of the app and the locale read of the [locale] layout; the app keeps its message catalogs and writes none of the stack.'
   '@starci/eslint-canon-be':
-    version: 3.15.1
+    version: 3.15.3
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.13.1
+    version: 9.13.3
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.18
+    version: 0.21.20
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.18
+    version: 0.21.20
     group: starci
     install: registry
     side: fe
@@ -127,14 +127,14 @@ pins:
     source: packages/nest-kit/package.json
     why: 'the module definition of every back-end module: defineConfigurableModule and defineCapabilityModule return the module base class, the options token and the options types with their types stated, so a <x>.module-definition.ts is one call that the lint on stated export types (R368) and the duplicate-code check (R21) both accept; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth':
-    version: 0.3.0
+    version: 0.4.0
     group: starci
     install: registry
     side: both
     source: packages/auth/package.json
     why: 'the lite sign-in: the NestJS module (EdDSA access tokens with a multi-key JWKS, passwords, Google OAuth with state and PKCE, rotating refresh sessions, the sign-in budget, the refresh cookie), the front-end client and its React bindings, the door contracts and test doubles; the one importer of the identity libraries, reached by a back end only through integrations/passport; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth-oidc':
-    version: 0.1.2
+    version: 0.1.3
     group: starci
     install: registry
     side: both
@@ -155,7 +155,7 @@ pins:
     source: packages/mail/package.json
     why: 'outgoing mail of a back end: a NestJS module and the Mailer port over SMTP (connect, greeting, socket and total timeouts, STARTTLS required by default, recipient, message and attachment checks, a shared SMTP target policy, coded errors, typed escaping render helpers returning { subject, text, html }), with @starci/mail/testing for its specs; the only importer of nodemailer (R90).'
   '@starci/hfs':
-    version: 5.5.1
+    version: 5.6.1
     group: starci
     install: registry
     side: both