@starci/hfs 5.2.0 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 5.4.0 - 2026-11-03
+
+- Fixed: `starci app sync --execute` never leaves an app uncompilable. Before it writes a managed TypeScript file or deletes a retired one, it compiles each front-end and back-end project with the change applied (the app's own TypeScript; the changed files and every file importing them, against what is on disk). A managed group whose render adds a type error, in its own files or in an app file that imports one, is held whole: `HFS_SYNC_GROUP_HELD`, exit 1, naming the group, its files and the first errors (what the app must add or still imports); the rest is written, and a side without TypeScript installed is named in a notice (`sync/compile-guard.mts`).
+- Fixed: `starci app codemod module-definition` drops every imported name the rewrite made unused (`ConfigurableModuleCls`, `ConfigurableModuleHost`, `ConfigurableModuleBuilder`), keeps the names the file still uses and `import type`, keeps the builder's JSDoc, and writes each file as the app's Prettier prints it, so no TS6133 and no prettier-hook refusal follow it (`codemod/app-prettier.mts`).
+- Changed: `starci app codemod account-doors --contract` says why it writes nothing: the contract migration is already in the chain, or no migration grants the app role on schema `auth`.
+- Changed: the lite sign-in renders `@starci/auth` 0.2.1: `identity_refresh_tokens.raced_count` in the baseline (the package's `identity-sessions.sql`), the refresh-token entity's `racedCount` and the session store's `markTokenRaced`. An app whose baseline holds the 0.2.0 tables adds `@starci/auth/migrations/identity-refresh-raced-successors.sql` as a migration.
+- Changed: the canon pins name `@starci/auth` 0.2.1, `@starci/auth-oidc` 0.1.1 and the Grammar family 0.21.16.
+- Upgrade, for an app on the CLI 1.1.0-alpha.49 / hfs 5.0.8 render moving to this version: (1) `npx starci app codemod module-definition --execute`, then `npm install`; (2) `npx starci app sync --execute`, which writes everything that compiles and holds the auth-lite sign-in glue while the app's own identity code differs, naming each missing or still-imported symbol; (3) adopt `@starci/mail` and make the identity domain provide what the held errors name; (4) `npx starci app sync --execute` again, which writes the glue once it compiles; (5) `npx starci app codemod account-doors --execute`, and `--contract` when the app still grants on schema `auth`; (6) add the `raced_count` migration above.
+
+## 5.3.0 - 2026-11-03
+
+- Fixed: the secrets family of the committed check cache stores codes, paths, positions and digests only (`cache/secret-records.mts`, `runtime/scripts/lib/secret-records.mts`), and the one secret judgement of R06 judges a file of `.starcistacks/cache/check/secrets/` by that contract, so `starci app check` can no longer write a cache the staged guard refuses (`HFS_PLAINTEXT_SECRET` for the `secrets/` folder name). A cache written before reads back as digests. Codemod: `starci app codemod secrets-cache`.
+- Added: `@starci/nest-kit` in the starter dependencies and in every module-definition template: a module definition is one call (`defineConfigurableModule<XOptions>()`, `defineCapabilityModule<XOptions>()` for a capability's representative module). The lint on stated export types (R368) accepts a destructured export of those two calls and no other; the digest of the file carries the call, so a change of the options type reaches the importers; `capability-module-shape` (R45) accepts the helper and `module-per-transport` confines it to the definition file. Codemod: `starci app codemod module-definition` rewrites the destructured and the typed builder forms and adds the dependency.
+- Fixed: `HFS_MONO_WORKSPACES` asks for `packages/*` after the fe workspaces once the app tracks a root package (slot `app.packages`, the module packages), so `starci app sync` and `starci app check` keep the entry `app add module` writes; the managed `test` and `build:be` scripts build the module packages first and the CI fast job runs `npm run test:modules` (PROJECT-3, BE-TEST-13).
+- Added: `starci app stack up` builds the harness runtime layer an app image stands on (`openclaw-runtime`) from the recipe this package ships (`stack/images/openclaw-runtime`, kept byte-equal to the harness `images/openclaw-runtime` by `npm run bundles`) when the host neither holds nor can pull it, as a governed heavy build.
+- Fixed: a secret member no creation rule of `.sops.yaml` reaches is refused `SECRET_SOPS_RULE_MISSING` before sops runs (a rule written for the legacy `.enc` spelling does not reach a `.enc.yaml` member), naming the path and `starci app secret init --env <env>`. Codemod: `starci app codemod sops-rules` migrates the legacy rule to the managed one (public recipients only).
+- Fixed: `starci app secret set` on a tooling member (`sonar.enc.yaml`, any member a service credential's custody path names) no longer declares it in `environments.<env>.secrets` (which made CI custody refuse the analysis token); it binds the member to its service (`credentials` and `ci.secrets`, the shape the template renders) or prints the exact binding. Codemod: `starci app codemod quality-binding` binds an app scaffolded before and names a runtime entry an earlier set declared.
+- Added: the lite starter depends on `@starci/mail` and renders the five email doors (BE `IdentityEmailService` and `identity_email_tokens`; FE `/auth/signup`, `/auth/resend`, `/auth/forgot`, `/auth/confirm`, `/auth/reset`, `EmailDoorForm`, the managed `modules/auth/email-doors.ts`), a Mailpit dev sink pinned by digest (`mail-sink.spec.mts`), and the stack links `@starci/mail` in the scaffold type-check.
+- Fixed: the `theme-tokens` codemod drops an alias whose rename would name itself (`--starci-core-accent: var(--accent)` became `--accent: var(--accent)`, which is invalid at computed-value time and blanked every brand colour) and a rule block that held only such aliases, with its comment; R61 now lists the stylelint rule `no-self-reference` (`@starci/stylelint-canon` 2.6.0) among its enforcers.
+- Changed: the scaffold type-check runs the back-end and front-end chains and both editions concurrently (the same checks, async spawns).
+- Fixed: an app's root workspace packages (`packages/agent-sdk`, `packages/module-<name>`, the managed `packages/modules`) are first-party packages of the import graph. A side imports one by its package name through the `exports` of its manifest: that is no import that leaves the side (`ARCH_INTERNAL_IMPORT_OUTSIDE` stopped the front-end lint run on `@scope/agent-sdk/workbench`) and adds no edge; an import into the package's source past its entry points stays refused, with a message that lists the entry points. The packages are read from the app root's `workspaces` (patterns that start with no side folder) and from the slots `app.packages` and `app.module-registry` (`architecture/root-packages.mts`, `rootPackages` of the architecture config). Spec: `architecture-root-packages.spec.mts`.
+- Added: the slots `app.packages`, `app.module-registry` and `app.packages-lint` in the runtime slot manifest (3.17.0; the first two were only in `contexts/hfs/slots.yaml`, so `packages/` classified as `HFS_SLOT_UNDECLARED`). `eslint.config.mjs` at the app root is the managed config of the root packages, no longer a forbidden tool config.
+- Added: `starci app sync` renders `eslint.config.mjs` at the app root whenever the app has a root package: the back-end canon over the back-end subpaths of `packages/<pkg>/src/**`, the front-end canon and the Grammar family's `<family>GrammarPackagesConfig` over `src/workbench/**` and `src/public/**`. `starci app check --gate lint` runs it as a third scope (`packages`, from the app root, uncached) beside `be` and `fe`. The package view of the slot resolver (`openPackagesHfsView`, `declaredPackagesHfsView` in `view.mts`) is the profile of a side over the paths of the app root; a package file is of the tier `package` and has no owner. Spec: `lint-packages.spec.mts`.
+- Changed: the lite sign-in and the email doors reach accounts through the account doors. The baseline migration includes `templates/app/auth-doors.sql.partial`, which is now the source of truth of the doors (it is no longer a byte copy of an app's own migration): eight SECURITY DEFINER functions `public.be_auth_user_by_email`, `_by_id`, `_by_google`, `be_auth_create_user`, `be_auth_link_google`, `be_auth_touch_user`, `be_auth_confirm_user(user, now)` (stamps the confirmation only, no sign-in record) and `be_auth_set_password(user, hash, confirm, now)` (sets the hash and, when `confirm` is true, confirms the mailbox), each with a pinned `search_path` and EXECUTE revoked from public, anon and authenticated and granted to `app_be` alone, plus a `lower(email)` index on `auth.users` the by-address door reads. `be_auth_set_password` is a four-argument function: an app that already has a three-argument one of its own keeps both. The three grants of `app_be` on schema `auth`, `auth.users` and `auth.identities` are gone from the baseline, so one injectable query no longer reaches every account's hash, role and metadata. The eight doors are in `ruleParams.be.dbFunctions`; an app lists none of them in hfs.json.
+- Changed: the managed identity glue (slot `be.identity.sign-in`): `AuthUserEntity` and `AuthIdentityEntity` are deleted; the account directory, the authenticator and `IdentityEmailService` (signup insert, mailbox confirm, password reset) call the doors through the new managed `persistence/account-doors.port.ts`, which validates every answer (`returnedRows`, `rowShape`); the database decides `disabled` at its own now() (a banned account no longer receives a reset mail). The rate counter over `identity_attempts` and the fail-closed refusal mapping are unchanged.
+- Added: `IdentitySignInService.endOthers(principal)` signs the caller out of every other device, and `Principal.sessionId` carries the device session of the access token. The authenticator logs an account created by Google sign-in as `identity.sign_in.account_created` (new managed `identity-sign-in.log-events.ts`) with the account id only. The lite starter carries `platform/database/database.client.ts` and exports `callDbFunction`.
+- Changed: R255 (`DB_APP_ROLE`) also refuses any grant to the declared back-end role on schema `auth`, on a table or sequence in it, or by default privilege for it, with no transition tolerance. The migrations are judged in order, so a later migration that revokes a grant clears it. BE-AUTH-2, BE-PERSISTENCE-4 and BE-PERSISTENCE-17 follow.
+- Added: `starci app codemod account-doors [--contract] [--execute]`, the upgrade of a lite app already on the template: it writes the expand migration `db/migrations/<ts>_account-doors.sql` with the doors the app lacks (a door is known by name and argument types, so an app that has the six earlier doors gets only the two new ones) and, with `--contract`, the migration `<ts>_contract_revoke-auth-grants.sql` that revokes the three grants from the declared role.
+- Changed: `starci app sync --execute` deletes the retired `auth-user.entity.ts` and `auth-identity.entity.ts` of an app on the old glue.
+- Upgrade, for a lite app scaffolded at 3.16.0 or later (the old glue grants `app_be` on `auth.users`): the new glue calls functions the app's database does not have until the expand migration is applied. Ship these three steps in one release, in this order; R255 reports the old grants until step 3 is in the chain, so they cannot ship apart.
+  1. `npx starci app codemod account-doors --execute` (expand): writes the migration that creates the doors the app lacks and the index.
+  2. `npx starci app sync --execute`: moves the glue onto the doors and deletes the two entity files; `npx starci app check` is green except R255 until step 3.
+  3. `npx starci app codemod account-doors --contract --execute` (contract): writes the migration that revokes the old grants. It refuses while an account door is undefined or a back-end source still maps `schema: "auth"`.
+  4. The deploy applies the expand migration before the services and the contract migration after the accept.
+  5. Rollback: the release before this one still reads the auth tables, so a rollback to it after the accept must restore the grants by hand, as the database owner:
+     ```sql
+     grant usage on schema auth to app_be;
+     grant select, insert, update on table auth.users to app_be;
+     grant select, insert on table auth.identities to app_be;
+     ```
+     (use the role `db.appRole` of hfs.json when it is not app_be). Revoke them again with the contract migration when the rollback is undone.
+  6. An app that already defines the six earlier doors (Nivo) runs step 1 too and gets only `be_auth_confirm_user` and the four-argument `be_auth_set_password`; its hfs.json `sides.be.dbFunctions` may drop the doors, which the canon now lists.
+
 ## 5.2.0 - 2026-11-03
 
 - Added: a scaffolded app of each edition type-checks and builds on every side (`scaffold-type-check.spec.mts`: one install per edition, `tsc` of the back end and its specs, the back-end build, the workspace packages, `tsc` and `next build` of each front-end app). The templates follow the Grammar contract: `Link` and `Page` for `SiteShell` and `NotFoundNotice`, a callable `toast`, the session reducers as a type, explicit next-intl navigation generics, optional access to the test world's apps and connections, no unused import in the migrations fixture. The lite dev api process no longer runs `--transpile-only`.

package/README.md

@@ -148,7 +148,7 @@ Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service
 
 The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `EVENT_BUS` -> `recordingEventBus()`, `QUEUE_OUTBOX` -> `recordingQueueOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
 
-`starci app check` runs ESLint once per side through the app's installed managed flat config: the backend canon on `be/`, and the universal FE canon plus the explicitly selected Grammar-family package on `fe/`. It also reads the app's `hfs.json` and tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and runs the whole architecture machine over each side folder. HFS findings carry their why code and Vietnamese text (`modules/kernel/failure-codes.yaml`); ESLint findings retain their rule id and failure code.
+`starci app check` runs ESLint once per side through the app's installed managed flat config: the backend canon on `be/`, and the universal FE canon plus the explicitly selected Grammar-family package on `fe/`; an app with root workspace packages (`packages/agent-sdk`, `packages/module-<name>`) has a third run from the app root through the managed root `eslint.config.mjs` that `starci app sync` renders, over `packages/<pkg>/src/**` by subpath (the backend canon on everything but `src/workbench/` and `src/public/`, the workbench contract kept; the universal FE canon and the Grammar family on those two, the contract left out). It also reads the app's `hfs.json` and tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and runs the whole architecture machine over each side folder. HFS findings carry their why code and Vietnamese text (`modules/kernel/failure-codes.yaml`); ESLint findings retain their rule id and failure code.
 
 Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `starci app check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
 
@@ -207,6 +207,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `starci app sync --execute` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
+`starci app sync --execute` never leaves the app uncompilable (`sync/compile-guard.mjs`): before it writes a managed TypeScript source or deletes a retired one, the side's own TypeScript compiles the app with those writes over the disk, and a managed group (`managedBy`) whose writes add a type error, in its own files or in an app file that imports one, is held whole: `HFS_SYNC_GROUP_HELD` (exit 1) names the group, its files and the errors (the names the render reads that the app does not provide yet, or the names it drops that the app still imports), and the rest of the render is written. The held files stay `HFS_SYNC_DRIFT` until the app provides what the render reads and sync runs again; a side whose TypeScript is not installed is written and named in a notice.
 Each finding is reported once: the managed ESLint and stylelint factory configs under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
 The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:world`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is `starci app check --gate lint`: ESLint over each side with its canon and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
 (slot `app.task-graph`): it carries the task graph, which no preset can render.

package/cache/hfs-family.d.mts

@@ -1,11 +1,10 @@
 import type { HeavyNodeRun } from '../runtime/scripts/api/node/run-node.mjs';
 import { type MachineFn, type RepositoryResult } from '../runtime/scripts/hfs/check.mjs';
 import type { Presets } from '../sync/index.mjs';
+import { SECRETS_FOLDER, SECRET_CODES } from './secret-records.mjs';
 import type { CheckSession, FamilyReport } from './types.mjs';
 export declare const HFS_FOLDER = "check/hfs";
-export declare const SECRETS_FOLDER = "check/secrets";
-/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
-export declare const SECRET_CODES: ReadonlySet<string>;
+export { SECRETS_FOLDER, SECRET_CODES };
 /** What the structure pass answers. */
 export interface PassResult {
     /** The whole-app check result of the pass (the shape `printCheck` reads), or the slot result when only secrets were asked for. */

package/cache/hfs-family.mjs

@@ -16,15 +16,10 @@ import { withRuleMemo } from '../runtime/scripts/hfs/rule-memo.mjs';
 import { RecordSet, scopedStep } from './records.mjs';
 import { FILE_RULES_STEP, RULE_STEP_PREFIX, UNIT_STEP_PREFIX, createStructureMemo } from './structure-memo.mjs';
 import { makeReport } from './report.mjs';
+import { SECRETS_FOLDER, SECRET_CODES, safeSecretFinding, safeSecretRecords } from './secret-records.mjs';
 import { sideKey } from './side-key.mjs';
 export const HFS_FOLDER = 'check/hfs';
-export const SECRETS_FOLDER = 'check/secrets';
-/** The finding codes of the secrets family: plaintext secrets, sealed custody, untracked secret files. */
-export const SECRET_CODES = new Set([
-    'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_LITE_SECRET_CUSTODY', 'HFS_IDENTITY_CUSTODY',
-    'HFS_AGE_KEY_CUSTODY', 'RT_SECRET_TRACKED', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'SEALED_CUSTODY_LOCATION',
-    'APP_SECRET_IN_CI', 'CI_SECRET_SEALED', 'BE_LOG_SECRET', 'BE_SECRET_DEFAULT', 'HFS_DOCKER_SECRETS',
-]);
+export { SECRETS_FOLDER, SECRET_CODES };
 const compact = (finding) => ({
     path: finding.path ?? '.', line: finding.line ?? 0, column: finding.column ?? 0, rule: finding.code, message: String(finding.message ?? ''),
 });
@@ -169,8 +164,8 @@ export async function runStructurePass(session, input) {
         const secretDecision = session.decide('secrets');
         const prior = session.records(SECRETS_FOLDER);
         const secretFindings = result.findings.filter((finding) => SECRET_CODES.has(finding.code));
-        session.replace(SECRETS_FOLDER, findingRecords(secretFindings, session.index.hashOf.bind(session.index), 'secrets'));
-        secretsReport = makeReport({ family: 'secrets', mode: secretDecision.mode, reason: secretDecision.reason, checked: filesChecked, reused: filesReused, previous: prior.flatMap((record) => record.findings), current: secretFindings.map(compact) });
+        session.replace(SECRETS_FOLDER, safeSecretRecords(findingRecords(secretFindings, session.index.hashOf.bind(session.index), 'secrets')));
+        secretsReport = makeReport({ family: 'secrets', mode: secretDecision.mode, reason: secretDecision.reason, checked: filesChecked, reused: filesReused, previous: prior.flatMap((record) => record.findings.map(safeSecretFinding)), current: secretFindings.map((finding) => safeSecretFinding(compact(finding))) });
         session.report(secretsReport);
     }
     return { result, contracts, machineReused: reasons, report, secretsReport };

package/cache/secret-records.d.mts

@@ -0,0 +1,7 @@
+import { SECRETS_FOLDER, SECRET_CODES } from '../runtime/scripts/lib/secret-records.mjs';
+import type { CacheRecord, Finding } from './types.mjs';
+export { SECRETS_FOLDER, SECRET_CODES };
+/** A finding as the secrets cache stores it: the same code, path and position, the message as its digest. */
+export declare function safeSecretFinding(finding: Finding): Finding;
+/** The records as the secrets cache stores them: each finding safe, no `data`. */
+export declare function safeSecretRecords(records: readonly CacheRecord[]): CacheRecord[];

package/cache/secret-records.mjs

@@ -0,0 +1,12 @@
+// secret-records.mts - the writer side of the secrets records contract (runtime/scripts/lib/secret-records.mts): the cache is committed, so the
+// records of `check/secrets` are projected to codes, paths, positions and digests before they are stored or compared, whoever produced them.
+import { messageDigest, SECRETS_FOLDER, SECRET_CODES } from '../runtime/scripts/lib/secret-records.mjs';
+export { SECRETS_FOLDER, SECRET_CODES };
+/** A finding as the secrets cache stores it: the same code, path and position, the message as its digest. */
+export function safeSecretFinding(finding) {
+    return { path: finding.path, line: finding.line, column: finding.column, rule: finding.rule, message: messageDigest(finding.message) };
+}
+/** The records as the secrets cache stores them: each finding safe, no `data`. */
+export function safeSecretRecords(records) {
+    return records.map((record) => ({ path: record.path, step: record.step, hash: record.hash, findings: record.findings.map(safeSecretFinding) }));
+}

package/cache/session.mjs

@@ -8,6 +8,7 @@ import { createContentIndex } from './content-index.mjs';
 import { computeFingerprint, fingerprintDifferences, parseFingerprint, serializeFingerprint } from './fingerprint.mjs';
 import { hashFile } from './hash.mjs';
 import { groupByArea, parseRecords, serializeRecords } from './jsonl.mjs';
+import { SECRETS_FOLDER, safeSecretRecords } from './secret-records.mjs';
 import { readCacheDir, resolveTrust, verifyCommitted } from './trust.mjs';
 import { CACHE_DIR } from './types.mjs';
 /** `STARCI_APP_CHECK_CACHE`: `full` ignores the cache (the release gate sets it), `verify` is read by the caller (runs diff, then full, compares). */
@@ -122,10 +123,11 @@ export function createDiskSession(options) {
             return global() ?? { mode: 'diff', reason: `against ${trust.reason}` };
         },
         records(folder) {
-            return replaced.get(folder)?.records ?? trustedRecords(folder);
+            return replaced.get(folder)?.records ?? (folder === SECRETS_FOLDER ? safeSecretRecords(trustedRecords(folder)) : trustedRecords(folder));
         },
         replace(folder, records, replaceOptions) {
-            replaced.set(folder, { records, depth: replaceOptions?.depth ?? 2 });
+            // The secrets family never stores secret material, whoever produced the records (secret-records.mts).
+            replaced.set(folder, { records: folder === SECRETS_FOLDER ? safeSecretRecords(records) : records, depth: replaceOptions?.depth ?? 2 });
         },
         unchanged: (paths, captured) => paths.every((file) => {
             const now = hashFile(path.join(root, file));

package/codemod/account-doors.d.mts

@@ -0,0 +1,36 @@
+/** One migration the codemod writes (or would write). */
+export interface AccountDoorsChange {
+    file: string;
+    phase: 'expand' | 'contract';
+    why: string;
+}
+/** One case left for a person. */
+export interface AccountDoorsFinding {
+    file: string;
+    reason: string;
+}
+/** The report of the upgrade (`starci app codemod account-doors`). */
+export interface AccountDoorsReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    phase: 'expand' | 'contract';
+    changes: AccountDoorsChange[];
+    findings: AccountDoorsFinding[];
+    next: string[];
+}
+/**
+ * Upgrade of a lite app that signs in over direct grants on auth.users and auth.identities to the account doors. The expand step (default)
+ * writes the migration that creates the doors the app lacks, with the text the lite baseline includes; the app then runs `starci app sync --execute`
+ * (the sign-in glue switches to the doors and the two entity files go). The contract step (`contract`) writes the migration that revokes the three
+ * grants, once the doors exist and no be source maps the auth tables; R255 reports the grants until that migration is in the chain. Nothing is written while a case is left for a person, and a step that is already
+ * done changes nothing.
+ */
+export declare function migrateAccountDoors({ root, write, contract, now }: {
+    root: string;
+    write?: boolean;
+    contract?: boolean;
+    now?: () => number;
+}): AccountDoorsReport;
+/** Render the migrations and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function accountDoorsMarkdown(report: AccountDoorsReport): string;

package/codemod/account-doors.mjs

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { nextStamp } from '../db/new.mjs';
+import { MIGRATIONS_DIR } from '../runtime/scripts/hfs/rules/database-constants.mjs';
+import { filesUnder, relativePosix } from './source-tree.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** The owner of the account doors: the partial the lite baseline includes, byte for byte. */
+const DOORS_PARTIAL = path.join(PACKAGE_ROOT, 'templates', 'app', 'auth-doors.sql.partial');
+/** A grant to anyone on schema auth or on a table in it. */
+const AUTH_GRANT = /\bgrant\b[^;]*?\bon\b\s+(?:schema\s+auth\b|(?:table\s+)?auth\.)/iu;
+const EXPAND_NAME = 'account-doors';
+const CONTRACT_NAME = 'contract_revoke-auth-grants';
+const SOURCE = /\.[cm]?tsx?$/iu;
+const ENTITY_FILES = ['auth-user.entity.ts', 'auth-identity.entity.ts'];
+/** The argument types of a signature, the `p_` parameter names dropped and case and spacing folded: a door is known by its name and types alone. */
+const typesOf = (args) => args.split(',').map((arg) => arg.trim().replace(/^p_\w+\s+/u, '').replace(/\s+/gu, ' ').toLowerCase()).join(', ');
+/** The partial split into its head (the comment and the index) and its doors, in the partial's order. */
+function partialParts(text) {
+    const lines = text.split('\n');
+    const doors = [...text.matchAll(/^(?:-- [^\n]*\n)?CREATE FUNCTION public\.(\w+)\(([^)]*)\)[\s\S]*?\$\$;\n/gmu)].map((match) => {
+        const own = lines.filter((line) => /^(?:REVOKE|GRANT) EXECUTE ON FUNCTION public\.(\w+)\(/u.exec(line)?.[1] === match[1] && typesOf(/\(([^)]*)\)/u.exec(line)[1]) === typesOf(match[2]));
+        return { name: match[1], types: typesOf(match[2]), block: match[0], grants: `${own.join('\n')}\n` };
+    });
+    return { head: text.slice(0, text.indexOf(doors[0].block)), doors };
+}
+/** The doors a text defines, as name(types) keys. */
+const definedDoors = (statements) => [...statements.matchAll(/create\s+(?:or\s+replace\s+)?function\s+public\.(\w+)\s*\(([^)]*)\)/giu)].map((match) => `${match[1].toLowerCase()}(${typesOf(match[2])})`);
+const migrationsOf = (root) => {
+    const dir = path.join(root, MIGRATIONS_DIR);
+    return fs.existsSync(dir) ? fs.readdirSync(dir).filter((name) => name.endsWith('.sql')).sort() : [];
+};
+const textOf = (root, name) => fs.readFileSync(path.join(root, MIGRATIONS_DIR, name), 'utf8');
+/** The statements of a migration, its line comments left out. */
+const statementsOf = (root, name) => textOf(root, name).replace(/--[^\n]*/gu, '');
+/** The application role hfs.json declares (`db.appRole`), app_be by default. */
+function appRoleOf(root) {
+    const role = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8')).db?.appRole;
+    return typeof role === 'string' && /^[a-z_][a-z0-9_]*$/u.test(role) ? role : 'app_be';
+}
+/** The be source that still maps or names the auth tables: an entity of schema auth, or the retired entity files. */
+function accountTableReferences(root) {
+    const be = path.join(root, 'be', 'src');
+    if (!fs.existsSync(be))
+        return [];
+    return filesUnder(be, SOURCE).map((file) => relativePosix(root, file)).filter((file) => {
+        const retired = ENTITY_FILES.some((name) => file.endsWith(`/${name}`));
+        return retired || /schema:\s*["']auth["']/u.test(fs.readFileSync(path.join(root, file), 'utf8'));
+    });
+}
+function contractText(role) {
+    return [
+        '-- contract: the back end reaches auth.users and auth.identities through the account doors (public.be_auth_*), so the application role',
+        '-- gives up its direct grants. The release before the doors still reads those tables, so a rollback to it after the accept needs them granted again.',
+        `revoke select, insert, update on table auth.users from ${role};`,
+        `revoke select, insert on table auth.identities from ${role};`,
+        `revoke usage on schema auth from ${role};`,
+        '',
+    ].join('\n');
+}
+/**
+ * Upgrade of a lite app that signs in over direct grants on auth.users and auth.identities to the account doors. The expand step (default)
+ * writes the migration that creates the doors the app lacks, with the text the lite baseline includes; the app then runs `starci app sync --execute`
+ * (the sign-in glue switches to the doors and the two entity files go). The contract step (`contract`) writes the migration that revokes the three
+ * grants, once the doors exist and no be source maps the auth tables; R255 reports the grants until that migration is in the chain. Nothing is written while a case is left for a person, and a step that is already
+ * done changes nothing.
+ */
+export function migrateAccountDoors({ root, write = false, contract = false, now = Date.now }) {
+    const phase = contract ? 'contract' : 'expand';
+    const report = { schema: 'starci/account-doors-report@1', root, write, phase, changes: [], findings: [], next: [] };
+    const declaration = JSON.parse(fs.readFileSync(path.join(root, 'hfs.json'), 'utf8'));
+    if (declaration.edition !== 'lite') {
+        report.findings.push({ file: 'hfs.json', reason: 'the account doors belong to the lite edition; a full app signs in through its identity provider' });
+        return report;
+    }
+    const names = migrationsOf(root);
+    const parts = partialParts(fs.readFileSync(DOORS_PARTIAL, 'utf8'));
+    const defined = new Set(names.flatMap((name) => definedDoors(statementsOf(root, name))));
+    const missing = parts.doors.filter((door) => !defined.has(`${door.name}(${door.types})`));
+    const stamp = nextStamp(names, now());
+    if (!contract) {
+        if (!missing.length)
+            return report;
+        const file = `${MIGRATIONS_DIR}/${stamp}_${EXPAND_NAME}.sql`;
+        const kept = missing.length === parts.doors.length ? 'all' : missing.map((door) => door.name).join(', ');
+        report.changes.push({ file, phase, why: `creates the account doors the app lacks (${kept}; SECURITY DEFINER, pinned search_path, EXECUTE for the application role alone) and the lower(email) index the by-address door reads` });
+        report.next.push('run `npx starci app sync --execute` (the sign-in glue moves onto the doors and the retired entity files are deleted), then verify and release both together', 'then run `npx starci app codemod account-doors --contract --execute` to revoke the old grants (R255 reports them until that migration is in the chain) and release the three together');
+        const text = `${parts.head}${missing.map((door) => door.block).join('\n')}\n${missing.map((door) => door.grants).join('')}`;
+        if (write)
+            fs.writeFileSync(path.join(root, file), text, { flag: 'wx' });
+        return report;
+    }
+    if (missing.length)
+        report.findings.push({ file: MIGRATIONS_DIR, reason: `no migration defines the account doors ${missing.map((door) => door.name).join(', ')}: run the expand step first` });
+    for (const file of accountTableReferences(root)) {
+        report.findings.push({ file, reason: 'still maps or names the auth tables; run `npx starci app sync --execute` so the sign-in glue uses the doors, and release that before the contract migration' });
+    }
+    if (report.findings.length)
+        return report;
+    if (names.some((name) => name.includes(`_${CONTRACT_NAME}`))) {
+        report.next.push('the contract migration is already in the chain: nothing is left to revoke');
+        return report;
+    }
+    if (!names.some((name) => AUTH_GRANT.test(statementsOf(root, name)))) {
+        report.next.push('no migration grants the application role on schema auth (the app reached accounts through the doors from the start): nothing to revoke');
+        return report;
+    }
+    const file = `${MIGRATIONS_DIR}/${stamp}_${CONTRACT_NAME}.sql`;
+    report.changes.push({ file, phase, why: 'revokes the direct grants on schema auth, auth.users and auth.identities from the application role' });
+    report.next.push('the deploy applies it right after the accept; the release before the doors cannot sign in after a rollback unless the grants are given back');
+    if (write)
+        fs.writeFileSync(path.join(root, file), contractText(appRoleOf(root)), { flag: 'wx' });
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the migrations and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function accountDoorsMarkdown(report) {
+    const out = ['# account-doors', '', `Step ${report.phase}: ${report.changes.length} migration${report.changes.length === 1 ? '' : 's'} ${report.write ? 'written' : 'to write'}, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | reason |', '|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(finding.file)} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Migrations', '', '| file | step | why |', '|---|---|---|');
+        for (const change of report.changes)
+            out.push(`| ${cell(change.file)} | ${change.phase} | ${cell(change.why)} |`);
+        out.push('');
+    }
+    if (report.next.length)
+        out.push('## Next', '', ...report.next.map((line) => `- ${line}`), '');
+    return `${out.join('\n')}\n`;
+}

package/codemod/app-prettier.d.mts

@@ -0,0 +1,5 @@
+import { type Prettier } from '../sync/format.mjs';
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+export declare function prettierOf(root: string, folders: readonly string[]): Prettier | undefined;
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+export declare function formatted(prettier: Prettier, root: string, file: string, text: string): Promise<string>;

package/codemod/app-prettier.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadPrettier } from '../sync/format.mjs';
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+export function prettierOf(root, folders) {
+    for (const folder of [...folders, root]) {
+        try {
+            return loadPrettier(folder);
+        }
+        catch { /* the next folder */ }
+    }
+    return undefined;
+}
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+export async function formatted(prettier, root, file, text) {
+    const ignorePath = path.join(root, '.prettierignore');
+    try {
+        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
+        if (info.ignored || !info.inferredParser)
+            return text;
+        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
+        return await prettier.format(text, { ...options, filepath: file });
+    }
+    catch {
+        return text;
+    }
+}

package/codemod/explicit-surface.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { declarationSurface, isEmittableSource } from '../runtime/scripts/lib/declaration-surface.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
-import { loadPrettier } from '../sync/format.mjs';
+import { formatted, prettierOf } from './app-prettier.mjs';
 import { applyEdits, importEdits } from './explicit-surface-edit.mjs';
 import { conventionType, MAX_TYPE_LENGTH, renderType } from './explicit-surface-render.mjs';
 import { GENERATED, relativePosix, sideFolders } from './source-tree.mjs';
@@ -212,30 +212,6 @@ async function sideSources(root, side, folder) {
     visit(folder);
     return { files: files.sort(), scope: selects === undefined ? 'walk' : 'canon' };
 }
-/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
-function prettierOf(root, folders) {
-    for (const folder of [...folders, root]) {
-        try {
-            return loadPrettier(folder);
-        }
-        catch { /* the next folder */ }
-    }
-    return undefined;
-}
-/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
-async function formatted(prettier, root, file, text) {
-    const ignorePath = path.join(root, '.prettierignore');
-    try {
-        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
-        if (info.ignored || !info.inferredParser)
-            return text;
-        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
-        return await prettier.format(text, { ...options, filepath: file });
-    }
-    catch {
-        return text;
-    }
-}
 /** The side-relative name a report gives `absolute`. */
 const nameOf = (root, absolute) => relativePosix(root, absolute);
 /** Plans every open file of one program, checks that the rewritten files read no worse than the originals, and returns what each file becomes. */

package/codemod/main.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { accountDoorsMarkdown, migrateAccountDoors } from './account-doors.mjs';
 import { codemodMain as buttonIntentMain } from './button-intent.mjs';
 import { migratePageNavigation, pageNavigationMarkdown } from './page-navigation.mjs';
 import { loadingStatesMarkdown, migrateLoadingStates } from './loading-states.mjs';
@@ -9,10 +10,14 @@ import { migrateSpacingRoles, spacingRolesMarkdown } from './spacing-roles.mjs';
 import { migrateSurfaceCardKinds, surfaceCardKindsMarkdown } from './surface-card-kinds.mjs';
 import { explicitSurfaceMarkdown, migrateExplicitSurface } from './explicit-surface.mjs';
 import { directiveFirstMarkdown, migrateDirectiveFirst } from './directive-first.mjs';
+import { migrateModuleDefinition, moduleDefinitionMarkdown } from './module-definition.mjs';
+import { migrateQualityBinding, qualityBindingMarkdown } from './quality-binding.mjs';
+import { migrateSopsRules, sopsRulesMarkdown } from './sops-rules.mjs';
+import { migrateSecretsCache, secretsCacheMarkdown } from './secrets-cache.mjs';
 import { migrateThemeTokens, themeTokensMarkdown } from './theme-tokens.mjs';
 import { migrateTierBinding, tierBindingMarkdown } from './tier-binding.mjs';
 /** The codemods `starci app codemod` runs, by name. */
-export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first']);
+export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first', 'secrets-cache', 'module-definition', 'sops-rules', 'quality-binding', 'account-doors']);
 /** The arguments of every report-style `starci app codemod`: --execute, --json, --format and --out; any other is refused. */
 export function spacingRolesArguments(argv) {
     const options = { write: false, format: 'markdown' };
@@ -46,6 +51,18 @@ export function spacingRolesArguments(argv) {
 }
 /** One of the report-style codemods run at an app root: its report object and the Markdown of it. */
 function runCodemod(name, root, write) {
+    if (name === 'quality-binding') {
+        const report = migrateQualityBinding({ root, write });
+        return { report, markdown: qualityBindingMarkdown(report) };
+    }
+    if (name === 'sops-rules') {
+        const report = migrateSopsRules({ root, write });
+        return { report, markdown: sopsRulesMarkdown(report) };
+    }
+    if (name === 'secrets-cache') {
+        const report = migrateSecretsCache({ root, write });
+        return { report, markdown: secretsCacheMarkdown(report) };
+    }
     if (name === 'directive-first') {
         const report = migrateDirectiveFirst({ root, write });
         return { report, markdown: directiveFirstMarkdown(report) };
@@ -105,6 +122,19 @@ async function explicitSurfaceMain(argv, io) {
     const report = await migrateExplicitSurface({ root: path.resolve(io.cwd), write: options.write });
     return emit(options, { report, markdown: explicitSurfaceMarkdown(report) }, io);
 }
+/** `starci app codemod module-definition`: it formats each rewritten definition with the app's Prettier, which is asynchronous. */
+async function moduleDefinitionMain(argv, io) {
+    const options = reportArguments(argv);
+    const report = await migrateModuleDefinition({ root: path.resolve(io.cwd), write: options.write });
+    return emit(options, { report, markdown: moduleDefinitionMarkdown(report) }, io);
+}
+/** `starci app codemod account-doors [--contract]`: the expand migration of the account doors, or (a release later) the contract migration that revokes the old grants. */
+function accountDoorsMain(argv, io) {
+    const contract = argv.includes('--contract');
+    const options = reportArguments(argv.filter((arg) => arg !== '--contract'));
+    const report = migrateAccountDoors({ root: path.resolve(io.cwd), write: options.write, contract });
+    return emit(options, { report, markdown: accountDoorsMarkdown(report) }, io);
+}
 /**
  * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
  * that leaves a case for a person exits 1 with the complete report.
@@ -115,6 +145,10 @@ export function codemodMain(argv, io) {
         return buttonIntentMain(argv, io);
     if (name === 'explicit-surface')
         return explicitSurfaceMain(rest, io);
+    if (name === 'account-doors')
+        return accountDoorsMain(rest, io);
+    if (name === 'module-definition')
+        return moduleDefinitionMain(rest, io);
     if (name === undefined || !CODEMODS.includes(name))
         throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
     const options = reportArguments(rest);

package/codemod/module-definition.d.mts

@@ -0,0 +1,59 @@
+import type { Prettier } from '../sync/format.mjs';
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One definition the migration rewrites: which form it was written in, the helper it became and the names it exports. */
+export interface ModuleDefinitionChange {
+    file: string;
+    from: 'destructured builder' | 'typed builder';
+    helper: string;
+    names: string[];
+}
+/** One case left for a person. */
+export interface ModuleDefinitionFinding {
+    file: string;
+    line: number;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod module-definition`). */
+export interface ModuleDefinitionReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: ModuleDefinitionChange[];
+    findings: ModuleDefinitionFinding[];
+    /** The `@starci/nest-kit` requirement of the app's root package.json: added by `--execute` when a definition changed, then `npm install` resolves it. */
+    dependency: {
+        name: string;
+        version: string;
+        declared: boolean;
+        added: boolean;
+    };
+}
+/** Rewrite one definition file's text to the helper form; `text` unchanged when the file holds no definition the codemod can rewrite. */
+export declare function transformModuleDefinition({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: ModuleDefinitionChange[];
+    findings: ModuleDefinitionFinding[];
+};
+/** What `migrateModuleDefinition` takes: the app root, whether to write, and the compiler and formatter of the app (found in it when left out; `prettier: null` writes the codemod's own layout). */
+export interface ModuleDefinitionOptions {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+    prettier?: Prettier | null;
+}
+/**
+ * Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, each rewritten file formatted by the app's Prettier
+ * (so `app check --format` and the app's hook accept it as written), then the dependency in the root package.json.
+ */
+export declare function migrateModuleDefinition({ root, write, ts, prettier }: ModuleDefinitionOptions): Promise<ModuleDefinitionReport>;
+/** Render the rewrite and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function moduleDefinitionMarkdown(report: ModuleDefinitionReport): string;
+export {};