@starci/hfs 5.0.8 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 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`.
+- Added: the custody kind `ed25519-pem` of `local.custody` (the dev sign-in key is EdDSA); the lite dev environment names `AUTH_WEB_ORIGIN`.
+- Added: `starci app add module <name>` and `starci app remove module <name>`: a module package `packages/module-<name>` of the product's agent SDK (`./template`, `./manifest`, `./workbench`, `./public`), registered in the root `workspaces` and the back-end and front-end dependencies, listed in the managed registry package `packages/modules` that `starci app sync` renders and drift-checks. Slots `app.packages` and `app.module-registry` (manifest 3.17.0). The module packages enter the Sonar sources, the Codecov paths and a `build:modules` / `test:modules` script pair that the typecheck, the lint and the build run first.
+- Added: rule R374 (`STACKS_CODE_BIND_MOUNT`, `STACKS_IMAGE_BASE_UNPINNED`, `STACKS_IMAGE_BASE_NOT_FORK`, `STACKS_IMAGE_ENV_DIVERGES`): a customised service is an image built from `.starcistacks/images/<name>/` on the harness's pinned base, no bind-mounted code, the same image in every environment (PROJECT-STACKS-11).
+- Changed: FE-PACKAGES-2 (a shared package, a module's workbench included, draws only with Grammar) and BE-TEST-13 (a module package's logic is inside the 100 per file scope).
+- Added: the lite starter composes `@starci/auth`: it depends on the package and on none of the identity libraries, `integrations/passport` is the glue the slot lists (`passport.config.ts`, `passport.options.ts`, `passport.decorators.ts`, `passport.kit.ts`, `errors/`), the web app keeps one `@starci/auth/client` instance in `modules/auth/client.ts`, and the baseline migration holds the package's session tables (`identity_sessions`, `identity_refresh_tokens`) byte for byte.
+- Changed: `infraOwners` own `@nestjs/passport`, `passport*`, `@nestjs/jwt`, `jose` and `bcryptjs` by nobody and `@starci/auth` by `integrations/passport` alone (R328); the `own-jwks-principal` machine refuses a `jwtVerify` call anywhere in the app and requires the `@starci/auth/server` import in the passport integration (R329); `transport-owner` no longer admits an auth door in `modules/auth`; the `auth` stack concern names `@starci/auth` and forbids `jose`, `jwt-decode`, `next-auth`, `@auth/core`, `keycloak-js` and `oidc-client-ts`.
+- Changed: the lite stack templates name `AUTH_WEB_ORIGIN` and the Ed25519 signing key; `AUTH_JWT_PRIVATE_KEY` is an EdDSA key and the public key is derived from it.
+- Added: the lite starter signs in with no hand-written auth code. The managed slots `be.identity.sign-in`, `be.feature.auth` and `fe.modules.auth.client` render, from `templates/be/auth-lite` and `templates/fe/auth-lite`, the `/auth` doors (login, refresh, session, logout, Google start and callback, jwks), the entities of the session, attempt, user and identity tables, the session, account and rate stores, the authenticator, `IdentitySignInService`, their specs and the web app's `createAuthClient` client; an edit is `HFS_MANAGED_FILE_DRIFT`. The identity error family gains the sign-in codes, the passport family keeps its `PASSPORT_` codes.
+- Added: the slot field `managedOnly` (a slot that only lists files sync renders; the slot owning the path judges them). Manifest 3.16.0.
+- Changed: the sync and the scaffold count the back-end source files their own targets render, so the CI shard count and the coverage scope are the same before and after the targets are written (one sync leaves the app in sync).
+- Added: the canon pin of `@starci/auth` 0.1.0.
+- Added: `starci app stack prepare|doctor|up|status|logs|down|verify --env <env>` for a docker-compose (dev) environment, driven by the new `environments.<env>.local` block of application-stacks.yaml: ports, compose services and their health, the environment's own database role (the migrations run as it and the app role gets its own password), dev-only custody generators, least grants (`STACK_GRANT_<NAME>`), data directories (`STACK_DATA_DIR`, `${data}`), setup and seed commands (a seed runs after the migration or after readiness), native app processes, readiness and verification probes. `up --execute` is the one command (host table, custody, setup, services, database, migrate with a receipt, seed once, processes, readiness, origins); `prepare`, `up` and `down` are dry runs until `--execute`, `down` never removes a volume, `doctor` prints the owner-run install step per OS for each missing prerequisite and installs nothing. A swarm environment keeps the swarm verbs and refuses the dev-only ones.
+- Added: `starci app secret init --env <dev env> [--execute]` creates the dev-only values `local.custody` declares (hex, base64, password, uuid, rsa-pem, ec-pem), once: a sealed value is kept, a half-present pair is refused, a vps or production environment is refused.
+- Added: `db migrate` runs its client tools inside the database container named by `STARCI_DB_CONTAINER`, so a host without PostgreSQL client tools migrates a dev database.
+- Added: rules R372 (`STACKS_LOCAL_CONFIG_INVALID`, `STACKS_DEV_UNDECLARED`: a coherent local block, and a lite app declares its dev environment) and R373 (`STACKS_RUNBOOK_DOCKER_COMMAND`: the dev runbook names `starci app stack up --env <env>` and carries no docker command).
+- Changed: the lite skeleton's dev environment is `docker-compose` with a local block, a compose file and a runbook of the new verbs (it was a Swarm stack with illustrative digests); slot `app.starcistacks` admits `<env>/infra/compose/**` in lite; `add queue` in lite adds the Redis to the dev compose file and the queue settings to the dev processes.
+
+## 5.1.0
+
+- Added: `starci app codemod explicit-surface` writes the inferred type of every export the classifier counts as open (R368): return types, variable, parameter and property types, from the app's own TypeScript program. It prefers a named type the program exports, writes `ReactElement` for components and Next's `Metadata` for `generateMetadata`, adds merged type-only imports after a directive prologue, compiles the result beside the original and writes a file only when it gains no diagnostic, and reports (with a suggested fix) destructured exports and anonymous, computed, too long, `any`, unnameable and predicate types. Prettier of the app formats what is written.
+- Added: `starci app codemod directive-first` moves a `"use client"` or `"use server"` below another statement, or in the form `("use client")`, to the first statement of its module (R369).
+- Changed: the test-world declaration (R47, R89) is read in its typed form, `const world: TestWorldApi = defineTestWorld({ ... })` with `useTestWorld` and `useSandbox` exported typed from it, as well as in the destructured form; the template writes the typed form, and a config with neither is still refused.
+- Added: `template-surface.spec.mts` holds every TypeScript template to R368 and R369 (the front-end units are judged through their generators).
+- Changed: the scaffold templates write the type of every export (R368): Nest module definitions export each `ConfigurableModuleHost` member with its type, hooks name their result interface, async pages and layouts return `Promise<ReactElement>`, redux, zustand, next-intl and Apollo exports are typed, SQL texts are `SqlText`, entity and migration lists are `DatabaseConnectionOptions` members. A new app scaffolds clean under `explicit-export-surface`.
+- Added: `runtime/scripts/lib/declaration-surface.mjs`, the one classifier of a TypeScript file's exported type surface (the isolated declaration emit and the exports it cannot write without inference, with the JSX-only component exemption), and `runtime/scripts/hfs/explicit-surface-rule.mjs`, the factory of the `explicit-export-surface` rule both lint canons build (R368). The app-check ESLint cache reads the same classifier for `open`, so the rule reports exactly the files the cache counts as open.
+- Changed: the ESLint child of the cached lint hands its project-graph snapshot out. The list runner (`lint/eslint-list.cjs`, now also the runner of a whole-side run, as the list `.`) asks each installed canon for `projectGraphSnapshot` after the lint and writes the findings beside its results; `lintSide` writes the `graph` records from them and builds the graph itself only for a canon the child did not answer for. A whole-side lint no longer builds the project graph a second time in the CLI process.
+
 ## 5.0.8
 
 - Removed: the `starci app lint` verb. `starci app check` is the one verb for app quality and carries what the lint verb carried: `--side be|fe` limits the lint gate to one side (reading and writing that side's cache records), `--out <file>` writes the merged Sonar Generic Issue Import document of the run (the findings of the selected gates under `starci-hfs`, then ESLint and stylelint), and `--fix` runs ESLint and stylelint with `--fix` before the check (with `--gate lint`). There is no `--changed` and no `--workspace`: the cache makes a whole-app check of an unchanged tree take seconds. The rendered `lint` and `lint:fix` scripts, the managed CI lint step and the release gate's Sonar row call `app check --gate lint`, and rule R13 requires that form.

package/README.md

@@ -24,10 +24,19 @@ starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [-
 starci app slot <path> [--cwd <dir>] [--json]
 starci app emit [--cwd <dir>]
 starci app db drift [--db-url-env <NAME>] [--json] [--cwd <dir>]
-starci app secret init | <set|get|unset|rename|remove|materialize|list|verify|recipients|migrate|split|audit|server-key> --env <env> ... [--cwd <dir>]
+starci app stack <prepare|up|down> --env <dev env> [--execute] | <doctor|status|verify> --env <dev env> | logs --env <dev env> --service <name> [--lines <n>]
+starci app secret init [--env <dev env> [--execute]] | <set|get|unset|rename|remove|materialize|list|verify|recipients|migrate|split|audit|server-key> --env <env> ... [--cwd <dir>]
 starci app ci secret set <NAME> [--from-custody] [--env <env>] [--repo <owner/name>] [--execute]
 ```
 
+**The dev environment in one command.** `starci app stack up --env dev --execute` brings a docker-compose environment up from its `local` block of
+`.starcistacks/application-stacks.yaml` (PROJECT-STACKS-6 of `contexts/project/stacks.md`): the host table (`doctor` prints the owner-run install
+step per OS for each missing prerequisite and installs nothing), the dev custody (`secret init --env dev --execute` creates the dev-only values once),
+the setup commands, the compose services and their health, the environment's own database role, the migrations with a receipt (`db migrate` runs its
+client tools in the database container named by `STARCI_DB_CONTAINER`, so the host needs no PostgreSQL client), the seed once, the native app
+processes, readiness and the origins. `prepare`, `up` and `down` are dry runs until `--execute`; `down` never removes a volume. State (process ids,
+logs, receipts) is under the state base (`STARCI_LOCAL_ROOT`), the opened custody under the private secrets directory outside the checkout.
+
 `starci app add` writes every front-end unit, in either edition, already in the shape of the harness's `contexts/code/fe`
 and `contexts/ui`, from `templates/fe/units`, with its copy in every catalog; nothing that exists is overwritten.
 

package/cache/import-graph.mjs

@@ -6,6 +6,7 @@
 // added or removed file and every file that reaches one through imports, in the new graph and in the recorded one. Everything here is pure over
 // its inputs (the compiler, a file reader, the hashes), so a spec drives it with fixtures and the cache itself stays in lint-family.mts.
 import path from 'node:path';
+import { DECLARATION, SCRIPT, TYPESCRIPT, declarationSurface } from '../runtime/scripts/lib/declaration-surface.mjs';
 import { hashText } from './hash.mjs';
 export const posix = (file) => file.replace(/\\/g, '/').replace(/^\.\//, '');
 /** The compiler options of the side's own tsconfig (the file the typed ESLint run reads), or the permissive defaults when the side holds none. */
@@ -120,58 +121,6 @@ export function resolveImports(host, options, file, text) {
     }
     return [...found].sort();
 }
-/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
-function isJsxValue(ts, expression) {
-    if (expression === undefined)
-        return false;
-    let node = expression;
-    while (ts.isParenthesizedExpression(node))
-        node = node.expression;
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
-        return true;
-    if (ts.isIdentifier(node))
-        return node.text === 'undefined';
-    return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
-}
-/**
- * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
- * reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
- * type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
- */
-function returnsOnlyJsx(ts, source, start) {
-    let found;
-    const find = (node) => {
-        if (found !== undefined || start < node.getFullStart() || start >= node.end)
-            return;
-        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
-        if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
-            found = node;
-            return;
-        }
-        ts.forEachChild(node, find);
-    };
-    find(source);
-    const fn = found;
-    if (fn === undefined || fn.type !== undefined || fn.body === undefined)
-        return false;
-    if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
-        return false;
-    if (!ts.isBlock(fn.body))
-        return isJsxValue(ts, fn.body);
-    let only = true;
-    const visit = (node) => {
-        if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
-            return;
-        if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
-            only = false;
-        ts.forEachChild(node, visit);
-    };
-    ts.forEachChild(fn.body, visit);
-    return only;
-}
-const SCRIPT = /\.(?:[cm]?jsx?)$/;
-const DECLARATION = /\.d\.[cm]?ts$/;
-const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
 /**
  * The type surface of one source file: the digest of its isolated declaration emit (`ts.transpileDeclaration`, TypeScript 5.5 and later, which reads the
  * file alone) and whether it is open. A body-only edit leaves the emit, and so the digest, as it was; a changed signature, export list or doc comment
@@ -184,16 +133,12 @@ export function surfaceOf(host, options, file, text) {
         return { api: hashText(text), open: true, refs: undefined };
     if (!TYPESCRIPT.test(file))
         return { api: hashText(text), open: false, refs: [] };
-    const emit = ts.transpileDeclaration;
-    if (emit === undefined)
-        return { api: undefined, open: true, refs: undefined };
     try {
-        const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(options.module === undefined ? {} : { module: options.module }) }, fileName: file, reportDiagnostics: true });
-        const diagnostics = (declared.diagnostics ?? []);
-        // a declaration whose only diagnostics are components returning JSX has the surface its emit shows
-        const source = diagnostics.length === 0 ? undefined : ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
-        const inferred = source !== undefined && !diagnostics.every((diagnostic) => (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start));
-        return { api: hashText(declared.outputText), open: inferred, refs: resolveImports(host, options, file, declared.outputText) };
+        const surface = declarationSurface(ts, file, text, options.module);
+        if (surface === null)
+            return { api: undefined, open: true, refs: undefined };
+        // the classifier is the one the explicit-export-surface rule of the canons reports with: a file is open exactly when it has a problem
+        return { api: hashText(surface.outputText), open: surface.problems.length > 0, refs: resolveImports(host, options, file, surface.outputText) };
     }
     catch {
         return { api: undefined, open: true, refs: undefined };

package/cache/lint-family.d.mts

@@ -78,10 +78,14 @@ export interface StylelintResult {
     warnings: StylelintWarning[];
     [key: string]: unknown;
 }
-/** The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. */
+/**
+ * The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. `graph` is, for ESLint, the project-graph
+ * snapshot each canon's graph rules built in the child, by canon name: the records of the `graph` step are written from it instead of building the graph again.
+ */
 export interface LinterOutcome<R> {
     results: R[];
     errors: string[];
+    graph?: Readonly<Record<string, GraphSnapshot>> | undefined;
 }
 /** Everything one side's cached lint needs. */
 export interface LintSideInput {
@@ -147,6 +151,11 @@ export declare function crossDigestFactory(options: {
 }): (file: string) => string | undefined;
 /** The TypeScript the app installed, resolved from the side folder like the linters are (not this package's own copy). */
 export declare function loadAppTypeScript(sideRoot: string): Ts;
+/**
+ * The graph findings of every canon that publishes graph rules, merged by file and sorted. A canon whose snapshot the ESLint child handed out (`handed`, by
+ * canon name) is not asked to build its graph again; any other canon builds it through its `projectGraph`.
+ */
+export declare function mergedSnapshot(sideRoot: string, canons: readonly CanonDeclarations[], handed?: Readonly<Record<string, GraphSnapshot>>): Record<string, GraphFinding[]> | null;
 /**
  * Judges one side: ESLint (and, for fe, stylelint) over what the records cannot vouch for, the records of the rest, and the new records.
  * Never throws for a tool failure: those come back in `errors`, and a side with an error stores nothing.

package/cache/lint-family.mjs

@@ -164,15 +164,20 @@ function graphHost(ts, sideRoot, hashOf) {
 }
 /** A record's `data` object, or an empty one. */
 const dataOf = (record) => (record.data !== null && typeof record.data === 'object' && !Array.isArray(record.data) ? record.data : {});
-/** The graph findings of every canon that publishes graph rules, merged by file and sorted. */
-function mergedSnapshot(sideRoot, canons) {
+/**
+ * The graph findings of every canon that publishes graph rules, merged by file and sorted. A canon whose snapshot the ESLint child handed out (`handed`, by
+ * canon name) is not asked to build its graph again; any other canon builds it through its `projectGraph`.
+ */
+export function mergedSnapshot(sideRoot, canons, handed) {
     const merged = {};
     for (const canon of canons) {
         if (!canon.graphRules)
             continue;
-        if (canon.projectGraph === null)
+        const given = handed?.[canon.name];
+        if (given === undefined && canon.projectGraph === null)
             return null;
-        for (const [file, findings] of Object.entries(canon.projectGraph({ repoRoot: sideRoot }).byFile))
+        const { byFile } = given ?? canon.projectGraph({ repoRoot: sideRoot });
+        for (const [file, findings] of Object.entries(byFile))
             merged[posix(file)] = [...(merged[posix(file)] ?? []), ...findings];
     }
     for (const list of Object.values(merged))
@@ -331,12 +336,14 @@ export async function lintSide(input) {
     // ------------------------------------------------------------------ the run
     const eslintList = [...dirtyEslint].sort();
     const styleList = [...dirtyStyle].sort();
+    let handedGraph;
     const freshEslint = new Map();
     const freshStyle = new Map();
     const rootOf = (file) => path.relative(sideRoot, file).replace(/\\/g, '/');
     if (eslintList.length > 0) {
         const run = await input.eslint(whole !== null ? null : eslintList);
         errors.push(...run.errors);
+        handedGraph = run.graph;
         for (const result of run.results)
             freshEslint.set(posix(rootOf(result.filePath)), result);
     }
@@ -408,7 +415,7 @@ export async function lintSide(input) {
                 if (!moved.has(file))
                     records.push({ path: file, step: LINT_STEPS.imports, hash: node.hash, findings: [], data: { globals: node.declaresGlobals, imports: node.imports, ...(node.api === undefined ? {} : { api: node.api }), open: node.open !== false, ...(node.refs === undefined ? {} : { refs: node.refs }) } });
             }
-            snapshot ??= mergedSnapshot(sideRoot, input.canons);
+            snapshot ??= mergedSnapshot(sideRoot, input.canons, handedGraph);
             for (const [file, findings] of Object.entries(snapshot ?? {})) {
                 if (scopeSet.has(file) && !moved.has(file) && findings.length > 0)
                     records.push({ path: file, step: LINT_STEPS.graph, hash: planHash(file), findings: graphRecordFindings(side, file, findings) });

package/codemod/directive-first.d.mts

@@ -0,0 +1,48 @@
+/** 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 move of the report: a directive taken from `line` to the top of its module. */
+export interface DirectiveFirstChange {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    from: string;
+    to: string;
+}
+/** One case left for a person. */
+export interface DirectiveFirstFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod directive-first`). */
+export interface DirectiveFirstReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: DirectiveFirstChange[];
+    findings: DirectiveFirstFinding[];
+}
+/** Move every `"use client"` / `"use server"` that is not in the prologue of the module to the top of it, as its first statement, with one blank line after. */
+export declare function transformDirectiveFirst({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: DirectiveFirstChange[];
+    findings: DirectiveFirstFinding[];
+};
+/** Preview or apply the moves in one app (`be/`, `fe/`, or `src/` of a single-side app); a conflicting module is kept in the returned report. */
+export declare function migrateDirectiveFirst({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): DirectiveFirstReport;
+/** Render the moves and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function directiveFirstMarkdown(report: DirectiveFirstReport): string;
+export {};

package/codemod/directive-first.mjs

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+import { filesUnder, relativePosix, sideFolders } from './source-tree.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** The directives Next.js reads from the prologue of a module (R369, FE_DIRECTIVE_FIRST). */
+const DIRECTIVES = new Set(['use client', 'use server']);
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/i;
+const DECLARATION = /\.d\.[cm]?ts$/i;
+/** The string literal a statement is made of, through the parentheses Prettier wraps it in, or null. */
+function stringStatement(ts, statement) {
+    if (!ts.isExpressionStatement(statement))
+        return null;
+    let expression = statement.expression;
+    while (ts.isParenthesizedExpression(expression))
+        expression = expression.expression;
+    return ts.isStringLiteral(expression) ? expression : null;
+}
+/** The span to delete for `statement`: its own line when nothing else is on it (with a `;` Prettier put before a parenthesized statement), else the statement alone. */
+function removalSpan(text, statement, source) {
+    let start = statement.getStart(source);
+    let end = statement.end;
+    let from = start;
+    while (from > 0 && (text[from - 1] === ' ' || text[from - 1] === '\t'))
+        from -= 1;
+    if (text[from - 1] === ';' && (from - 1 === 0 || text[from - 2] === '\n'))
+        from -= 1;
+    const startsLine = from === 0 || text[from - 1] === '\n';
+    let to = end;
+    while (to < text.length && (text[to] === ' ' || text[to] === '\t'))
+        to += 1;
+    const endsLine = to >= text.length || text[to] === '\n' || text[to] === '\r';
+    if (startsLine && endsLine) {
+        start = from;
+        end = text[to] === '\r' ? to + 2 : to + 1;
+    }
+    return { start, end: Math.min(end, text.length) };
+}
+/** Move every `"use client"` / `"use server"` that is not in the prologue of the module to the top of it, as its first statement, with one blank line after. */
+export function transformDirectiveFirst({ ts, text, file = 'module.tsx' }) {
+    const none = { text, changes: [], findings: [] };
+    if (!text.includes('use client') && !text.includes('use server'))
+        return none;
+    const kind = /\.tsx$/i.test(file) ? ts.ScriptKind.TSX : /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : /\.[cm]?js$/i.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+    const first = source.statements[0];
+    if (first === undefined)
+        return none;
+    // The prologue is the run of plain string statements at the top; a parenthesized one is an expression, not a directive.
+    let prologueEnd = 0;
+    const kept = new Set();
+    while (prologueEnd < source.statements.length) {
+        const statement = source.statements[prologueEnd];
+        if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression))
+            break;
+        kept.add(statement.expression.text);
+        prologueEnd += 1;
+    }
+    const misplaced = source.statements.slice(prologueEnd).flatMap((statement, offset) => {
+        const literal = stringStatement(ts, statement);
+        return literal !== null && DIRECTIVES.has(literal.text) ? [{ statement, literal, before: prologueEnd + offset }] : [];
+    });
+    if (!misplaced.length)
+        return none;
+    const changes = [];
+    const findings = [];
+    const opposite = (directive) => (directive === 'use client' ? 'use server' : 'use client');
+    const wanted = new Set(misplaced.map(entry => entry.literal.text));
+    const edits = [];
+    const toTop = [];
+    const placed = new Set(kept);
+    for (const { statement, literal, before } of misplaced) {
+        const place = sourceLocation(source, statement);
+        const directive = literal.text;
+        if (kept.has(opposite(directive)) || wanted.has(opposite(directive))) {
+            findings.push({ file, ...place, code: 'CONFLICTING_DIRECTIVES', reason: `"use client" and "use server" cannot share a module: split it, then keep the one directive that stays at the top` });
+            continue;
+        }
+        edits.push({ ...removalSpan(text, statement, source), text: '' });
+        if (!placed.has(directive)) {
+            toTop.push(literal.getText(source) + (statement.getText(source).endsWith(';') ? ';' : ''));
+            placed.add(directive);
+        }
+        const mangled = ts.isExpressionStatement(statement) && ts.isParenthesizedExpression(statement.expression);
+        changes.push({ file, ...place, code: mangled ? 'DIRECTIVE_PARENTHESIZED' : 'DIRECTIVE_BELOW_STATEMENT', from: `${mangled ? 'parenthesized, ' : ''}after ${before} statement${before === 1 ? '' : 's'}`, to: 'first statement' });
+    }
+    if (toTop.length)
+        edits.push({ start: first.getStart(source), end: first.getStart(source), text: `${toTop.join('\n')}\n\n` });
+    let output = text;
+    for (const edit of edits.sort((a, b) => b.start - a.start || b.end - a.end))
+        output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+    return { text: output, changes, findings };
+}
+/** Preview or apply the moves in one app (`be/`, `fe/`, or `src/` of a single-side app); a conflicting module is kept in the returned report. */
+export function migrateDirectiveFirst({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('directive-first needs TypeScript installed in the app or @starci/hfs development checkout');
+    const folders = sideFolders(root);
+    if (!folders.length)
+        throw new Error('directive-first runs at an app root with a fe/ directory');
+    const report = { schema: 'starci/directive-first-report@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+    for (const target of folders.flatMap(folder => filesUnder(folder, SOURCE)).filter(target => !DECLARATION.test(target))) {
+        const file = relativePosix(root, target);
+        const original = fs.readFileSync(target, 'utf8');
+        const result = transformDirectiveFirst({ 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);
+        }
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the moves and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function directiveFirstMarkdown(report) {
+    const out = ['# directive-first', '', `Scanned ${report.filesScanned} files, ${report.filesChanged.length} ${report.write ? 'changed' : 'would change'}, ${report.changes.length} directives moved, ${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.column}`)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Moves', '', '| location | code | from | to |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(`${item.file}:${item.line}:${item.column}`)} | ${item.code} | ${cell(item.from)} | ${cell(item.to)} |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/explicit-surface-edit.d.mts

@@ -0,0 +1,14 @@
+import type { ImportNeed } from './explicit-surface-render.mjs';
+import type * as TsTypes from 'typescript';
+type Ts = typeof import('typescript');
+/** One text edit of the source: the span `start`..`end` becomes `text`. */
+export interface Edit {
+    start: number;
+    end: number;
+    text: string;
+}
+/** The edits that give a file the imports `needs` names: a specifier added to a named import of the same module, else one `import type` line per module. */
+export declare function importEdits(ts: Ts, source: TsTypes.SourceFile, text: string, needs: readonly ImportNeed[]): Edit[];
+/** `text` with `edits` applied, last position first so every offset stays true; edits at one position keep their order. */
+export declare function applyEdits(text: string, edits: readonly Edit[]): string;
+export {};

package/codemod/explicit-surface-edit.mjs

@@ -0,0 +1,57 @@
+/** The edits that give a file the imports `needs` names: a specifier added to a named import of the same module, else one `import type` line per module. */
+export function importEdits(ts, source, text, needs) {
+    if (!needs.length)
+        return [];
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const imports = source.statements.filter(ts.isImportDeclaration);
+    const first = imports[0];
+    const quote = first !== undefined && ts.isStringLiteral(first.moduleSpecifier) ? first.moduleSpecifier.getText(source).slice(0, 1) : '"';
+    const semicolon = first !== undefined && first.getText(source).endsWith(';') ? ';' : '';
+    const edits = [];
+    const lines = [];
+    const bySpecifier = new Map();
+    for (const need of needs)
+        bySpecifier.set(need.specifier, [...(bySpecifier.get(need.specifier) ?? []), need.name]);
+    for (const [specifier, names] of bySpecifier) {
+        const sorted = [...new Set(names)].sort();
+        const home = imports.find(declaration => ts.isStringLiteral(declaration.moduleSpecifier) && declaration.moduleSpecifier.text === specifier
+            && declaration.importClause?.namedBindings !== undefined && ts.isNamedImports(declaration.importClause.namedBindings) && declaration.importClause.namedBindings.elements.length > 0);
+        const clause = home?.importClause;
+        const bindings = clause?.namedBindings;
+        if (clause !== undefined && bindings !== undefined && ts.isNamedImports(bindings)) {
+            const last = bindings.elements[bindings.elements.length - 1];
+            edits.push({ start: last.end, end: last.end, text: sorted.map(name => `, ${clause.isTypeOnly ? '' : 'type '}${name}`).join('') });
+        }
+        else
+            lines.push(`import type { ${sorted.join(', ')} } from ${quote}${specifier}${quote}${semicolon}`);
+    }
+    if (lines.length)
+        edits.push(newImports(ts, source, text, lines, eol));
+    return edits;
+}
+/** The edit that adds whole import lines: after the last import, else after the directive prologue, else above the first statement. */
+function newImports(ts, source, text, lines, eol) {
+    const block = lines.join(eol);
+    const last = source.statements.filter(ts.isImportDeclaration).at(-1);
+    if (last !== undefined)
+        return { start: last.end, end: last.end, text: `${eol}${block}` };
+    let prologue;
+    for (const statement of source.statements) {
+        if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression))
+            break;
+        prologue = statement;
+    }
+    if (prologue !== undefined)
+        return { start: prologue.end, end: prologue.end, text: `${eol}${eol}${block}` };
+    const first = source.statements[0];
+    const at = first === undefined ? text.length : first.getStart(source);
+    return { start: at, end: at, text: `${block}${eol}${eol}` };
+}
+/** `text` with `edits` applied, last position first so every offset stays true; edits at one position keep their order. */
+export function applyEdits(text, edits) {
+    const ordered = edits.map((edit, at) => ({ edit, at })).sort((a, b) => b.edit.start - a.edit.start || b.edit.end - a.edit.end || b.at - a.at);
+    let output = text;
+    for (const { edit } of ordered)
+        output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+    return output;
+}

package/codemod/explicit-surface-names.d.mts

@@ -0,0 +1,30 @@
+import type * as TsTypes from 'typescript';
+/** The TypeScript compiler API of the app's own install, typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** What naming a type reads of the app: its compiler, program and one source file. */
+export interface NamingContext {
+    ts: Ts;
+    program: TsTypes.Program;
+    checker: TsTypes.TypeChecker;
+    options: TsTypes.CompilerOptions;
+    source: TsTypes.SourceFile;
+    /** The absolute, forward-slash name of the file being annotated. */
+    file: string;
+    text: string;
+}
+/** The source file of the program a module path (absolute, without its extension) names, or undefined. */
+export declare function moduleFile(c: NamingContext, modulePath: string): TsTypes.SourceFile | undefined;
+/** The symbol a module exports under `name`, with aliases resolved, or undefined. */
+export declare function exportedSymbol(c: NamingContext, file: TsTypes.SourceFile, name: string): TsTypes.Symbol | undefined;
+/** The declaration `symbol` stands for: an import resolved to what it imports, a local export to its export symbol, so two names of one declaration compare equal. */
+export declare function declarationOf(c: NamingContext, symbol: TsTypes.Symbol): TsTypes.Symbol;
+/** The names that can be written at `enclosing` without an import, as symbols; what a function body declares is not visible from its signature. */
+export declare function namesInScope(c: NamingContext, enclosing: TsTypes.Node): Map<string, TsTypes.Symbol>;
+/**
+ * `node` (the type node the checker wrote for `type`) with every anonymous object type that an exported type of the app stands for replaced by a
+ * reference to that type. It follows type arguments (`Promise<{...}>`), arrays and unions; any other anonymous part stays for the caller to refuse.
+ */
+export declare function nameAnonymousParts(c: NamingContext, node: TsTypes.TypeNode, type: TsTypes.Type, enclosing: TsTypes.Node): TsTypes.TypeNode;
+/** The directory-relative form of `target` from the folder of `from`, without extension, the way a relative import is written. */
+export declare function relativeSpecifier(from: string, target: string): string;
+export {};