@starci/hfs 5.1.0 → 5.3.0

package/codemod/module-definition.mjs

@@ -0,0 +1,242 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { filesUnder, relativePosix, sideFolders } from './source-tree.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const KIT = '@starci/nest-kit';
+const DEFINITION_FILE = /\.module-definition\.tsx?$/;
+const EXPORTED = new Set(['ConfigurableModuleClass', 'MODULE_OPTIONS_TOKEN', 'OPTIONS_TYPE', 'ASYNC_OPTIONS_TYPE']);
+const PRINT_WIDTH = 120;
+const unfit = (source, node, code, reason) => ({ reason, code, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1 });
+/** The builder expression `new ConfigurableModuleBuilder<X>(args).call().call()...` unwrapped to its `new` and the calls on it, in order; null when `expression` is not one. */
+function builderOf(ts, expression) {
+    const calls = [];
+    let node = expression;
+    while (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        calls.unshift({ name: node.expression.name.text, call: node });
+        node = node.expression.expression;
+    }
+    return ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'ConfigurableModuleBuilder' ? { created: node, calls } : null;
+}
+/** The text of a statement's own JSDoc comment (without the delimiters), or an empty string. */
+function docOf(ts, source, statement) {
+    const ranges = ts.getLeadingCommentRanges(source.text, statement.pos) ?? [];
+    const last = ranges.at(-1);
+    const text = last === undefined ? '' : source.text.slice(last.pos, last.end);
+    return text.startsWith('/**') ? text.slice(3, -2).replace(/^\s*\*\s?/gm, '').trim() : '';
+}
+/** Reads the builder part of a definition: options type, token, representative or not; a reason when the chain is not one the helpers stand for. */
+function readBuilder(ts, source, node) {
+    const built = builderOf(ts, node);
+    if (built === null)
+        return unfit(source, node, 'MODULE_DEFINITION_NOT_A_BUILDER', 'the definition is not `new ConfigurableModuleBuilder<XOptions>(...)` with its calls and `.build()`');
+    const { created, calls } = built;
+    const options = created.typeArguments?.[0];
+    if (options === undefined)
+        return unfit(source, created, 'MODULE_DEFINITION_UNTYPED', 'the builder states no options type; write `ConfigurableModuleBuilder<XOptions>` and run the codemod again');
+    let token = null;
+    const argument = created.arguments?.[0];
+    if (argument !== undefined) {
+        const only = ts.isObjectLiteralExpression(argument) && argument.properties.length === 1 ? argument.properties[0] : undefined;
+        if (only === undefined || !ts.isPropertyAssignment(only) || !ts.isIdentifier(only.name) || only.name.text !== 'optionsInjectionToken' || !ts.isIdentifier(only.initializer)) {
+            return unfit(source, argument, 'MODULE_DEFINITION_BUILDER_OPTIONS', 'the helpers take `optionsInjectionToken` as an identifier and no other builder setting; keep this definition and ask for the setting in @starci/nest-kit');
+        }
+        token = only.initializer.text;
+    }
+    const names = calls.map((entry) => entry.name);
+    if (names.at(-1) !== 'build')
+        return unfit(source, node, 'MODULE_DEFINITION_NOT_BUILT', 'the chain does not end in `.build()`');
+    const extra = names.filter((name) => name !== 'build' && name !== 'setExtras' && name !== 'setClassMethodName');
+    if (extra.length > 0)
+        return unfit(source, node, 'MODULE_DEFINITION_CHAIN', `\`.${extra[0]}(...)\` has no helper; the helpers define \`register\` (and \`isGlobal\` for a capability) only`);
+    const named = calls.find((entry) => entry.name === 'setClassMethodName');
+    const method = named?.call.arguments[0];
+    if (method !== undefined && !(ts.isStringLiteral(method) && method.text === 'register'))
+        return unfit(source, method, 'MODULE_DEFINITION_CHAIN', 'the class method is not "register"; static-module-register allows `register` only');
+    const extras = calls.find((entry) => entry.name === 'setExtras');
+    if (extras !== undefined) {
+        const defaults = extras.call.arguments[0];
+        const standard = defaults !== undefined && ts.isObjectLiteralExpression(defaults) && defaults.properties.length === 1
+            && ts.isPropertyAssignment(defaults.properties[0]) && defaults.properties[0].initializer.kind === ts.SyntaxKind.FalseKeyword
+            && defaults.properties[0].name.getText(source) === 'isGlobal';
+        if (!standard)
+            return unfit(source, extras.call, 'MODULE_DEFINITION_CHAIN', 'the extras are not `{ isGlobal: false }`; the capability helper is the one standard shape');
+    }
+    return { options: options.getText(source), token, representative: extras !== undefined };
+}
+/** The reading of one definition file, in either written form, or why it is left alone (null: no definition here, nothing to do). */
+function readDefinition(ts, source) {
+    const statements = [...source.statements];
+    // The destructured form: `export const { A, B } = new ConfigurableModuleBuilder<X>()....build()`.
+    for (const statement of statements) {
+        if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        const declaration = statement.declarationList.declarations[0];
+        if (declaration === undefined || !ts.isObjectBindingPattern(declaration.name) || declaration.initializer === undefined || builderOf(ts, declaration.initializer) === null)
+            continue;
+        const read = readBuilder(ts, source, declaration.initializer);
+        if ('reason' in read)
+            return read;
+        const names = [];
+        for (const element of declaration.name.elements) {
+            if (!ts.isIdentifier(element.name) || element.propertyName !== undefined || element.dotDotDotToken !== undefined || !EXPORTED.has(element.name.text))
+                return unfit(source, element, 'MODULE_DEFINITION_NAMES', 'a name is renamed, spread or not one of ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE');
+            names.push(element.name.text);
+        }
+        return { ...read, names, doc: docOf(ts, source, statement), drop: new Set(), at: statement, from: 'destructured builder' };
+    }
+    // The typed form: `const built = new ConfigurableModuleBuilder<X>()....build()`, `type Host = ConfigurableModuleHost<...>`, `export const A: Host["A"] = built.A`.
+    const builtStatement = statements.find((statement) => ts.isVariableStatement(statement) && statement.declarationList.declarations.some((declaration) => declaration.initializer !== undefined && builderOf(ts, declaration.initializer) !== null));
+    if (builtStatement === undefined || !ts.isVariableStatement(builtStatement))
+        return null;
+    const declaration = builtStatement.declarationList.declarations[0];
+    if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
+        return unfit(source, builtStatement, 'MODULE_DEFINITION_NOT_A_BUILDER', 'the builder is not bound to one name');
+    const read = readBuilder(ts, source, declaration.initializer);
+    if ('reason' in read)
+        return read;
+    const local = declaration.name.text;
+    const drop = new Set([builtStatement]);
+    const names = [];
+    let doc = '';
+    let at = null;
+    for (const statement of statements) {
+        if (ts.isTypeAliasDeclaration(statement) && ts.isTypeReferenceNode(statement.type) && ts.isIdentifier(statement.type.typeName) && statement.type.typeName.text === 'ConfigurableModuleHost') {
+            drop.add(statement);
+            continue;
+        }
+        if (!ts.isVariableStatement(statement) || statement === builtStatement)
+            continue;
+        const exported = statement.declarationList.declarations[0];
+        const initializer = exported?.initializer;
+        const typed = initializer !== undefined && ts.isPropertyAccessExpression(initializer) && ts.isIdentifier(initializer.expression) && initializer.expression.text === local && ts.isIdentifier(initializer.name);
+        if (exported === undefined || !typed || !ts.isIdentifier(exported.name) || initializer.name.text !== exported.name.text || !EXPORTED.has(exported.name.text))
+            continue;
+        names.push(exported.name.text);
+        drop.add(statement);
+        if (at === null) {
+            at = statement;
+            doc = docOf(ts, source, statement);
+        }
+    }
+    if (at === null || names.length === 0)
+        return unfit(source, builtStatement, 'MODULE_DEFINITION_NAMES', 'the built definition is not re-exported by name (`export const ConfigurableModuleClass: Host["ConfigurableModuleClass"] = built.ConfigurableModuleClass`)');
+    drop.delete(at);
+    // Anything else that still reads `built` or `Host` would break once they are gone.
+    const stillUsed = statements.some((statement) => !drop.has(statement) && statement !== at && !ts.isImportDeclaration(statement) && /\b(?:built|Host)\b/.test(statement.getText(source)));
+    if (stillUsed)
+        return unfit(source, builtStatement, 'MODULE_DEFINITION_NAMES', 'another statement of the file reads the builder result or `Host`');
+    return { ...read, names: [...names].sort((a, b) => [...EXPORTED].indexOf(a) - [...EXPORTED].indexOf(b)), doc, drop, at, from: 'typed builder' };
+}
+/** The one export of the new definition, laid out the way Prettier prints it at the width of the canon (break the arguments of a call that takes a token, else after the `=`). */
+function exportLine(reading, helper) {
+    const head = `export const { ${reading.names.join(', ')} } =`;
+    const call = `${helper}<${reading.options}>(${reading.token === null ? '' : `{ optionsInjectionToken: ${reading.token} }`})`;
+    if (`${head} ${call}`.length <= PRINT_WIDTH)
+        return `${head} ${call}`;
+    return reading.token === null ? `${head}\n    ${call}` : `${head} ${helper}<${reading.options}>({\n    optionsInjectionToken: ${reading.token},\n})`;
+}
+/** The import declaration of `@nestjs/common` without the builder names, or null when nothing else is imported from it. */
+function nestImport(ts, source, statement) {
+    const bindings = statement.importClause?.namedBindings;
+    if (bindings === undefined || !ts.isNamedImports(bindings))
+        return statement.getText(source);
+    const kept = bindings.elements.filter((element) => !['ConfigurableModuleBuilder', 'ConfigurableModuleHost'].includes((element.propertyName ?? element.name).text));
+    if (kept.length === bindings.elements.length)
+        return statement.getText(source);
+    if (kept.length === 0 && statement.importClause?.name === undefined)
+        return null;
+    return `import { ${kept.map((element) => element.getText(source)).join(', ')} } from "@nestjs/common"`;
+}
+/** Rewrite one definition file's text to the helper form; `text` unchanged when the file holds no definition the codemod can rewrite. */
+export function transformModuleDefinition({ ts, text, file = 'x.module-definition.ts' }) {
+    const none = { text, changes: [], findings: [] };
+    if (!text.includes('ConfigurableModuleBuilder'))
+        return none;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const read = readDefinition(ts, source);
+    if (read === null)
+        return none;
+    if ('reason' in read)
+        return { ...none, findings: [{ file, line: read.line, code: read.code, reason: read.reason }] };
+    const helper = read.representative ? 'defineCapabilityModule' : 'defineConfigurableModule';
+    const imports = [`import { ${helper} } from "${KIT}"`];
+    const body = [];
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const nest = ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === '@nestjs/common' ? nestImport(ts, source, statement) : statement.getText(source);
+            if (nest !== null)
+                imports.push(nest);
+            continue;
+        }
+        if (read.drop.has(statement))
+            continue;
+        if (statement === read.at) {
+            body.push(`${read.doc === '' ? '' : `/** ${read.doc} */\n`}${exportLine(read, helper)}`);
+            continue;
+        }
+        body.push(text.slice(statement.pos, statement.end).replace(/^\s*\n/, '').trimEnd());
+    }
+    const output = `${imports.join('\n')}\n\n${body.join('\n\n')}\n`;
+    return { text: output, changes: [{ file, from: read.from, helper, names: read.names }], findings: [] };
+}
+/** The `@starci/nest-kit` requirement the codemod adds to an app's root package.json. */
+function kitVersion() {
+    return bundledPins()[KIT]?.version ?? '0.1.0';
+}
+/** Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, then the dependency in the root package.json. */
+export function migrateModuleDefinition({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('module-definition needs TypeScript installed in the app or @starci/hfs development checkout');
+    const folders = sideFolders(root);
+    if (!folders.length)
+        throw new Error('module-definition runs at an app root with a be/ directory');
+    const packageFile = path.join(root, 'package.json');
+    const manifest = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, 'utf8')) : null; // reason: package.json parsed from disk, only dependencies is read
+    const declared = manifest?.dependencies?.[KIT] !== undefined;
+    const report = { schema: 'starci/module-definition-report@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [], dependency: { name: KIT, version: kitVersion(), declared, added: false } };
+    for (const target of folders.flatMap((folder) => filesUnder(folder, DEFINITION_FILE))) {
+        const file = relativePosix(root, target);
+        const original = fs.readFileSync(target, 'utf8').replace(/\r\n/g, '\n');
+        const result = transformModuleDefinition({ ts, text: original, file });
+        report.filesScanned += 1;
+        report.changes.push(...result.changes);
+        report.findings.push(...result.findings);
+        if (result.text !== original) {
+            report.filesChanged.push(file);
+            if (write)
+                fs.writeFileSync(target, result.text);
+        }
+    }
+    if (report.filesChanged.length > 0 && !declared && manifest !== null) {
+        report.dependency.added = write;
+        if (write) {
+            manifest.dependencies = Object.fromEntries(Object.entries({ ...manifest.dependencies, [KIT]: report.dependency.version }).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+            fs.writeFileSync(packageFile, `${JSON.stringify(manifest, null, 2)}\n`);
+        }
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the rewrite and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function moduleDefinitionMarkdown(report) {
+    const out = ['# module-definition', '', `Scanned ${report.filesScanned} definitions, ${report.filesChanged.length} ${report.write ? 'rewritten' : 'would be rewritten'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(`${finding.file}:${finding.line}`)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Rewritten', '', '| file | from | helper | names |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(item.file)} | ${item.from} | ${item.helper} | ${cell(item.names.join(', '))} |`);
+        out.push('');
+    }
+    if (report.filesChanged.length > 0 && !report.dependency.declared) {
+        out.push('## Dependency', '', report.dependency.added ? `\`${KIT}@${report.dependency.version}\` was added to package.json: run \`npm install\`.` : `\`${KIT}@${report.dependency.version}\` is added to package.json by \`--execute\`; then run \`npm install\`.`, '');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/quality-binding.d.mts

@@ -0,0 +1,33 @@
+/** One tooling member the migration bound to its service. */
+export interface QualityBindingChange {
+    environment: string;
+    member: string;
+    service: string;
+    keys: string[];
+}
+/** One case left for a person: a binding the edit cannot place, or a runtime entry to delete. */
+export interface QualityBindingFinding {
+    environment: string;
+    member: string;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod quality-binding`). */
+export interface QualityBindingReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    changes: QualityBindingChange[];
+    findings: QualityBindingFinding[];
+}
+/**
+ * Bind the sealed tooling members of an app scaffolded before the binding was rendered (sonar.enc.yaml with `services.sonar.credentials: []`) to their
+ * service: the credential and the `ci.secrets` entry the template shows. A runtime `environments.<env>.secrets` entry an earlier `starci app secret set`
+ * declared for such a member is named for the owner to delete, since CI custody refuses a CI secret granted at runtime (APP_SECRET_IN_CI).
+ */
+export declare function migrateQualityBinding({ root, write }: {
+    root: string;
+    write?: boolean;
+}): QualityBindingReport;
+/** Render the binding and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function qualityBindingMarkdown(report: QualityBindingReport): string;

package/codemod/quality-binding.mjs

@@ -0,0 +1,38 @@
+import { bindToolingMembers } from '../runtime/scripts/hfs/secret-standard.mjs';
+/**
+ * Bind the sealed tooling members of an app scaffolded before the binding was rendered (sonar.enc.yaml with `services.sonar.credentials: []`) to their
+ * service: the credential and the `ci.secrets` entry the template shows. A runtime `environments.<env>.secrets` entry an earlier `starci app secret set`
+ * declared for such a member is named for the owner to delete, since CI custody refuses a CI secret granted at runtime (APP_SECRET_IN_CI).
+ */
+export function migrateQualityBinding({ root, write = false }) {
+    const report = { schema: 'starci/quality-binding-report@1', root, write, changes: [], findings: [] };
+    for (const item of bindToolingMembers(root, write)) {
+        if (item.outcome.bound.length > 0)
+            report.changes.push({ environment: item.environment, member: item.member, service: item.service, keys: item.outcome.bound });
+        else if (!write && item.outcome.remedy !== '')
+            report.changes.push({ environment: item.environment, member: item.member, service: item.service, keys: [] });
+        else if (item.outcome.remedy !== '')
+            report.findings.push({ environment: item.environment, member: item.member, code: 'QUALITY_BINDING_BY_HAND', reason: item.outcome.remedy });
+        if (item.runtimeEntries.length > 0)
+            report.findings.push({ environment: item.environment, member: item.member, code: 'QUALITY_RUNTIME_ENTRY', reason: `environments.${item.environment}.secrets declares ${item.runtimeEntries.join(', ')} for the tooling member ${item.member}; delete the entry, the token is read by CI through services.${item.service}.credentials` });
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the binding and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function qualityBindingMarkdown(report) {
+    const out = ['# quality-binding', '', `${report.changes.length} tooling member(s) ${report.write ? 'bound' : 'would be bound'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| environment | member | code | reason |', '|---|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${finding.environment} | ${finding.member} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Bound', '', '| environment | member | service |', '|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${item.environment} | ${item.member} | ${item.service} |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/secrets-cache.d.mts

@@ -0,0 +1,35 @@
+/** One cache file the migration rewrites: the records whose message became a digest or whose payload was dropped. */
+export interface SecretsCacheChange {
+    file: string;
+    records: number;
+    messagesDigested: number;
+    payloadsDropped: number;
+}
+/** One case left for a person: a file whose lines the migration cannot turn into the contract's records. */
+export interface SecretsCacheFinding {
+    file: string;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod secrets-cache`). */
+export interface SecretsCacheReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: SecretsCacheChange[];
+    findings: SecretsCacheFinding[];
+}
+/**
+ * Migrate the secrets cache of one app to the record contract of the secrets family (contexts/project/check-cache.md, "The secrets records"):
+ * every message becomes its digest and a record's `data` is dropped, in the canonical form the cache writes. The migration needs no run of
+ * the gate, because the digest of a message is the identity the family compares; a file it cannot read as records is left for a person, who
+ * deletes it and runs `starci app check --gate secrets`.
+ */
+export declare function migrateSecretsCache({ root, write }: {
+    root: string;
+    write?: boolean;
+}): SecretsCacheReport;
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function secretsCacheMarkdown(report: SecretsCacheReport): string;

package/codemod/secrets-cache.mjs

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseRecords, serializeRecords } from '../cache/jsonl.mjs';
+import { safeSecretRecords } from '../cache/secret-records.mjs';
+import { SECRETS_CACHE_FILE, secretRecordFaults } from '../runtime/scripts/lib/secret-records.mjs';
+import { relativePosix } from './source-tree.mjs';
+const CACHE_FOLDER = '.starcistacks/cache/check/secrets';
+/** Every file of the secrets cache folder under `root`, app-relative and sorted. */
+function cacheFiles(root) {
+    const folder = path.join(root, CACHE_FOLDER);
+    if (fs.statSync(folder, { throwIfNoEntry: false })?.isDirectory() !== true)
+        return [];
+    return fs.readdirSync(folder, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => relativePosix(root, path.join(entry.parentPath, entry.name)))
+        .filter((file) => SECRETS_CACHE_FILE.test(file))
+        .sort();
+}
+/**
+ * Migrate the secrets cache of one app to the record contract of the secrets family (contexts/project/check-cache.md, "The secrets records"):
+ * every message becomes its digest and a record's `data` is dropped, in the canonical form the cache writes. The migration needs no run of
+ * the gate, because the digest of a message is the identity the family compares; a file it cannot read as records is left for a person, who
+ * deletes it and runs `starci app check --gate secrets`.
+ */
+export function migrateSecretsCache({ root, write = false }) {
+    const report = { schema: 'starci/secrets-cache-report@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+    for (const file of cacheFiles(root)) {
+        report.filesScanned += 1;
+        const target = path.join(root, file);
+        const original = fs.readFileSync(target, 'utf8');
+        const parsed = parseRecords(original);
+        if (parsed.invalid > 0) {
+            report.findings.push({ file, code: 'SECRETS_CACHE_UNREADABLE', reason: `${parsed.invalid} line${parsed.invalid === 1 ? ' is' : 's are'} not a cache record; delete the file and run starci app check --gate secrets` });
+            continue;
+        }
+        const migrated = safeSecretRecords(parsed.records);
+        const text = serializeRecords(migrated);
+        const remaining = secretRecordFaults(text);
+        if (remaining.length > 0) {
+            report.findings.push({ file, code: 'SECRETS_CACHE_NOT_MIGRATABLE', reason: `${remaining[0] ?? 'a record'}; delete the file and run starci app check --gate secrets` });
+            continue;
+        }
+        if (text === original)
+            continue;
+        const digested = parsed.records.reduce((count, record, index) => count + record.findings.filter((finding, at) => finding.message !== migrated[index]?.findings[at]?.message).length, 0);
+        report.filesChanged.push(file);
+        report.changes.push({ file, records: parsed.records.length, messagesDigested: digested, payloadsDropped: parsed.records.filter((record) => record.data !== undefined).length });
+        if (write)
+            fs.writeFileSync(target, text);
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function secretsCacheMarkdown(report) {
+    const out = ['# secrets-cache', '', `Scanned ${report.filesScanned} cache files, ${report.filesChanged.length} ${report.write ? 'migrated' : 'would be migrated'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| file | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(finding.file)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Migrated', '', '| file | records | messages digested | payloads dropped |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(item.file)} | ${item.records} | ${item.messagesDigested} | ${item.payloadsDropped} |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/sops-rules.d.mts

@@ -0,0 +1,34 @@
+/** One creation rule the migration rewrites: the rule's index, the path_regex it had and the one it has. */
+export interface SopsRuleChange {
+    rule: number;
+    from: string;
+    to: string;
+}
+/** One case left for a person. */
+export interface SopsRuleFinding {
+    file: string;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod sops-rules`). */
+export interface SopsRulesReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    file: string;
+    changes: SopsRuleChange[];
+    findings: SopsRuleFinding[];
+}
+/** The path_regex a managed `.sops.yaml` carries for a rule written with `from`, or `from` when it is already managed or is no member rule. */
+export declare function managedPathRegex(from: string): string;
+/**
+ * Migrate a legacy `.sops.yaml` to the form `starci app secret init --env` writes (public recipients only, a rule per member spelling): a rule whose
+ * path_regex matches the legacy `.enc` spelling alone also matches `.enc.yaml`, the spelling `secret set` writes, which sops otherwise refuses with
+ * no creation rule. Recipients and the other rules are kept; nothing private is read or written.
+ */
+export declare function migrateSopsRules({ root, write }: {
+    root: string;
+    write?: boolean;
+}): SopsRulesReport;
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function sopsRulesMarkdown(report: SopsRulesReport): string;

package/codemod/sops-rules.mjs

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml, stringifyYaml } from '../runtime/engine/yaml.mjs';
+const FILE = '.sops.yaml';
+/** The rule an earlier `secret init` wrote: it matches the legacy `.enc` spelling of a member only. */
+const LEGACY = String.raw `\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc$`;
+/** The rule `secret init` writes now: both spellings of a member (`.enc` and `.enc.yaml`), every environment. */
+const CURRENT = String.raw `\.starcistacks[/\\][^/\\]+[/\\]secrets[/\\][^/\\]+\.enc(?:\.yaml)?$`;
+/** A per-environment rule written for the legacy spelling alone: `.enc$` where the managed form ends `.enc(?:\.yaml)?$`. */
+const LEGACY_END = String.raw `\.enc$`;
+const MODERN_END = String.raw `\.enc(?:\.yaml)?$`;
+/** The path_regex a managed `.sops.yaml` carries for a rule written with `from`, or `from` when it is already managed or is no member rule. */
+export function managedPathRegex(from) {
+    if (from === LEGACY)
+        return CURRENT;
+    return /secrets/.test(from) && from.endsWith(LEGACY_END) ? `${from.slice(0, -LEGACY_END.length)}${MODERN_END}` : from;
+}
+/**
+ * Migrate a legacy `.sops.yaml` to the form `starci app secret init --env` writes (public recipients only, a rule per member spelling): a rule whose
+ * path_regex matches the legacy `.enc` spelling alone also matches `.enc.yaml`, the spelling `secret set` writes, which sops otherwise refuses with
+ * no creation rule. Recipients and the other rules are kept; nothing private is read or written.
+ */
+export function migrateSopsRules({ root, write = false }) {
+    const report = { schema: 'starci/sops-rules-report@1', root, write, file: FILE, changes: [], findings: [] };
+    const target = path.join(root, FILE);
+    if (!fs.existsSync(target))
+        return report;
+    let config;
+    try {
+        config = parseYaml(fs.readFileSync(target, 'utf8'));
+    }
+    catch {
+        config = null;
+    }
+    if (config === null || typeof config !== 'object' || !Array.isArray(config.creation_rules)) {
+        report.findings.push({ file: FILE, code: 'SOPS_RULES_UNREADABLE', reason: `${FILE} holds no creation_rules list; write it with starci app secret init --env <env>` });
+        return report;
+    }
+    config.creation_rules.forEach((rule, index) => {
+        if (typeof rule?.path_regex !== 'string')
+            return;
+        const to = managedPathRegex(rule.path_regex);
+        if (to === rule.path_regex)
+            return;
+        report.changes.push({ rule: index, from: rule.path_regex, to });
+        rule.path_regex = to;
+    });
+    if (report.changes.length > 0 && write)
+        fs.writeFileSync(target, stringifyYaml(config));
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migration and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function sopsRulesMarkdown(report) {
+    const out = ['# sops-rules', '', `${report.changes.length} creation rule(s) ${report.write ? 'migrated' : 'would be migrated'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| file | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(finding.file)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Migrated', '', '| rule | from | to |', '|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${item.rule} | \`${cell(item.from)}\` | \`${cell(item.to)}\` |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/theme-tokens.mjs

@@ -23,12 +23,51 @@ const KEPT = /^--(?:offset-pop-shadow-ink|starci-core-(?:mark-(?:danger|warning)
 const PRIVATE = /--(starci-core|offset-pop)-([a-z][a-z0-9-]*)/g;
 /** The mapped name of one private token, or null when HeroUI has no token for it. */
 const mapped = (prefix, name) => (prefix === 'starci-core' ? CORE_TOKENS : OFFSET_POP_TOKENS)[name] ?? null;
+/**
+ * The lines left once the self-referential aliases are dropped (`null` marks a dropped line): the blank lines that would sit just before a
+ * closing brace go, and a rule block left empty goes with the selector lines and the comment that introduced it.
+ */
+function tidyDropped(lines) {
+    const kept = [];
+    let dropped = false;
+    for (const line of lines) {
+        if (line === null) {
+            dropped = true;
+            continue;
+        }
+        if (dropped && /^\s*\}\s*$/.test(line)) {
+            while ((kept[kept.length - 1] ?? 'x').trim() === '')
+                kept.pop();
+            const open = kept.length - 1;
+            if (open >= 0 && /\{\s*$/.test(kept[open] ?? '') && !/^\s*@/.test(kept[open] ?? '')) {
+                let start = open;
+                while (start > 0 && /,\s*$/.test(kept[start - 1] ?? ''))
+                    start -= 1;
+                if (start > 0 && /\*\/\s*$/.test(kept[start - 1] ?? '')) {
+                    let comment = start - 1;
+                    while (comment > 0 && !/^\s*\/\*/.test(kept[comment] ?? ''))
+                        comment -= 1;
+                    start = comment;
+                }
+                kept.length = start;
+                while (kept.length > 0 && (kept[kept.length - 1] ?? '').trim() === '')
+                    kept.pop();
+                dropped = false;
+                continue;
+            }
+        }
+        if (line.trim() !== '' || !dropped)
+            dropped = false;
+        kept.push(line);
+    }
+    return kept;
+}
 /** One stylesheet or component file rewritten; `changes` and `findings` carry 1-based lines. */
 export function transformThemeTokens({ text, file = '' }) {
     const changes = [];
     const findings = [];
     const isCss = file.endsWith('.css') || file === '';
-    const lines = text.split('\n').map((line, index) => {
+    const mappedLines = text.split('\n').map((line, index) => {
         const number = index + 1;
         let out = line;
         if (isCss) {
@@ -55,6 +94,13 @@ export function transformThemeTokens({ text, file = '' }) {
                 changes.push({ file, line: number, from: token, to: `--${to}` });
                 return `--${to}`;
             });
+            // `--starci-core-accent: var(--accent)` became `--accent: var(--accent)`: a custom property that names itself is invalid at computed-value
+            // time and blanks the colour, and the grammar reads HeroUI's token directly, so the alias is dropped, not renamed.
+            const self = /^\s*(--[a-z][a-z0-9-]*)\s*:\s*var\(\s*(--[a-z][a-z0-9-]*)\s*\)\s*;?\s*$/.exec(out);
+            if (self !== null && self[1] === self[2] && out !== line) {
+                changes.push({ file, line: number, from: line.trim(), to: '(dropped: the alias names itself)' });
+                return null;
+            }
         }
         else {
             const root = /<(?:Core|OffsetPop)?GrammarRoot\b[^>]*\btheme=/.exec(line);
@@ -63,7 +109,7 @@ export function transformThemeTokens({ text, file = '' }) {
         }
         return out;
     });
-    return { text: lines.join('\n'), changes, findings };
+    return { text: tidyDropped(mappedLines).join('\n'), changes, findings };
 }
 function sourceFiles(dir) {
     return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {

package/db/postgres.mjs

@@ -35,7 +35,15 @@ export function dbTarget(ctx, name = DEFAULT_DB_URL_ENV) {
     const parsed = parseConnection(value);
     if (!parsed)
         throw refusal('DB_URL_INVALID', `${name} is not a postgres connection URL`);
-    return { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
+    const target = { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
+    // A dev environment's database runs in its own container (starci app stack up): STARCI_DB_CONTAINER runs the client tools inside it, so the host needs no PostgreSQL client.
+    const container = ctx.env.STARCI_DB_CONTAINER;
+    if (!container)
+        return target;
+    const inside = inContainer(target, container);
+    const url = new URL(inside.url);
+    url.port = '5432';
+    return { ...target, ...inside, kind: 'url', urlEnv: name, url: url.toString() };
 }
 /** Where a `-f` file of an in-container target is copied before the client reads it. */
 const CONTAINER_DIR = '/tmp/starci-db';

package/lint/run.d.mts

@@ -56,6 +56,12 @@ export declare const ESLINT_HEAP_ENV = "STARCI_ESLINT_HEAP_MB";
 export declare function eslintHeapArgs(env?: NodeJS.ProcessEnv): string[];
 /** A linter's json results through the app's own install, run from `cwd` (a side folder): `{ results }` or `{ error }`. The child runs while the caller goes on. */
 export declare function runLinter({ cwd, pkg, bin, args, bound, list, files, graph }: LinterSpec, execute?: HeavyNodeRun): Promise<LinterRun>;
+/**
+ * The root workspace packages of an app (`packages/<pkg>/src/**`) are linted by the managed `eslint.config.mjs` of the app root, as a third scope beside
+ * the two sides: its files are app-relative and its working directory is the app root. It has a scope only while the config is there.
+ */
+export declare const PACKAGES = "packages";
+export declare const PACKAGES_CONFIG = "eslint.config.mjs";
 /**
  * The lint scope a flat config declares: `ignored(file)` for its global ignores (a block holding only `ignores` and `name`), which prune
  * the walk, and `source(file)` for a file some block's `files` select while that block's own `ignores` do not (standard flat-config