@starci/hfs 5.1.0 → 5.3.0

package/scaffold/add-queue-lite.mjs

@@ -79,13 +79,11 @@ const template = (relative) => read(path.join(TEMPLATES_DIR, ...relative.split('
 const DATABASE_ERROR = 'be/src/modules/platform/database/errors/database.error.ts';
 /** Skeleton files the lite starter leaves out and the queue capabilities use, each from its skeleton template. */
 const SKELETON_FILES = Object.freeze([
-    ['be/src/modules/platform/database/database.client.ts', 'skeleton-lite/src/modules/platform/database/database.client.ts'],
-    ['be/src/modules/platform/database/database.client.spec.ts', 'skeleton-lite/src/modules/platform/database/database.client.spec.ts'],
     ['be/src/modules/platform/database/database.sql.ts', 'skeleton-lite/src/modules/platform/database/database.sql.ts'],
     ['be/src/modules/platform/primitives/sequence.policy.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.ts'],
     ['be/src/modules/platform/primitives/sequence.policy.spec.ts', 'skeleton/src/modules/platform/primitives/sequence.policy.spec.ts'],
 ]);
-/** The database-function call and the sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
+/** The sql tag of the outbox and claim statements (with its identifier error) and the in-order relay the queue adapters walk their rows with. */
 function skeletonFiles(repoRoot) {
     const created = SKELETON_FILES.filter(([relative]) => !fs.existsSync(path.join(repoRoot, ...relative.split('/'))))
         .map(([relative, source]) => ({ relative, text: render(template(`be/${source}`), {}) }));
@@ -300,6 +298,54 @@ function keysPatch(file) {
     lines.splice(last + 1, 0, ...KEY_ROWS);
     return { file, text: lines.join('\n') };
 }
+const DEV_REDIS_PORT = 56379;
+/** The redis service a dev compose file gains: loopback only, append-only, on the host port the environment declares. */
+const devRedisService = `  redis:
+    image: ${REDIS_IMAGE}
+    command: ["redis-server", "--appendonly", "yes"]
+    ports:
+      - "127.0.0.1:\${STACK_PORT_REDIS}:6379"
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+    restart: unless-stopped
+`;
+/**
+ * A docker-compose dev environment (runtime docker-compose, a `local` block) runs the declared Redis from its compose file, on its own loopback
+ * port, and the queue processes reach it there: the compose service, the port, the service entry and the api and worker processes' queue settings.
+ */
+function devQueuePatches(repoRoot, manifest, edit, consumers) {
+    const patches = [];
+    const dev = Object.entries(manifest?.environments ?? {}).filter(([, environment]) => environment?.runtime === 'docker-compose' && environment.local);
+    for (const [name, environment] of dev) {
+        const composeRelative = `.starcistacks/${name}/${environment.composeFiles?.[0] ?? 'infra/compose/compose.yaml'}`;
+        const composeFile = path.join(repoRoot, ...composeRelative.split('/'));
+        const compose = read(composeFile).replace(/\r\n/g, '\n');
+        if (/^ {2}redis:/m.test(compose))
+            continue;
+        const base = ['environments', name];
+        const value = edit.value.environments[name];
+        edit.append([...base, 'components'], `redis: {port: ${DEV_REDIS_PORT}}\n`);
+        value.components.redis = { port: DEV_REDIS_PORT };
+        edit.append([...base, 'local', 'ports'], `redis: ${DEV_REDIS_PORT}\n`);
+        value.local.ports.redis = DEV_REDIS_PORT;
+        edit.append([...base, 'local', 'services'], '- {name: redis, wait: healthy}\n');
+        value.local.services.push({ name: 'redis', wait: 'healthy' });
+        for (const run of value.local.processes ?? []) {
+            if (!consumers.includes(run.name))
+                continue;
+            edit.append([...base, 'local', 'processes', { item: 'name', is: run.name }, 'env'], 'QUEUE_ENABLED: "true"\nQUEUE_REDIS_HOST: 127.0.0.1\nQUEUE_REDIS_PORT: "${port.redis}"\n');
+            Object.assign(run.env, { QUEUE_ENABLED: 'true', QUEUE_REDIS_HOST: '127.0.0.1', QUEUE_REDIS_PORT: '${port.redis}' });
+        }
+        const head = compose.includes('\nvolumes:\n') ? compose.replace('\nvolumes:\n', `\n${devRedisService}volumes:\n`) : `${compose.replace(/\n*$/, '\n')}${devRedisService}volumes:\n`;
+        patches.push({ file: composeFile, text: `${head.replace(/\n*$/, '\n')}  redis-data: {}\n` });
+    }
+    return patches;
+}
 /** Every stack file the declared Redis adds to or changes, planned before anything is written. */
 function stackFiles(repoRoot, { project, consumers }) {
     const manifestRelative = '.starcistacks/application-stacks.yaml';
@@ -330,6 +376,7 @@ function stackFiles(repoRoot, { project, consumers }) {
         if (!fs.existsSync(path.join(repoRoot, ...recovery.split('/'))))
             created.push({ relative: recovery, text: recoveryRecord });
     }
+    patches.push(...devQueuePatches(repoRoot, manifest, edit, consumers));
     patches.unshift({ file: manifestFile, text: edit.text() });
     return { patches: patches.filter((patch) => patch !== null), created, environments: swarm.map(([name]) => name) };
 }

package/scaffold/add.mjs

@@ -23,6 +23,7 @@ import { ScaffoldError, pascalOf } from './service.mjs';
 import { addTable, graphqlPlatformFiles } from './add-table.mjs';
 import { addModuleImport, compositionCode, readComposeGroup, writeComposeGroup } from './add-compose.mjs';
 import { addApp } from './add-app.mjs';
+import { addModule } from './add-module.mjs';
 import { FE_UNIT_LAYERS, addFeUnit } from './add-fe-unit.mjs';
 import { addFePage } from './add-fe-page.mjs';
 import { addFeOverlay } from './add-fe-overlay.mjs';
@@ -57,6 +58,10 @@ export function addKind({ repoRoot, noun, name, options = {}, now = Date.now })
         const result = addApp({ root: repoRoot, name });
         return { ...result, registered: { patterns: [], kinds: [] } };
     }
+    if (noun === 'module') {
+        const result = addModule({ root: repoRoot, name });
+        return { created: [...result.created, ...result.updated], registered: { patterns: [], kinds: [] } };
+    }
     const feOwner = FE_OWNERS[noun];
     if (feOwner !== undefined || Object.hasOwn(FE_UNIT_LAYERS, noun)) {
         const result = feOwner === undefined ? addFeUnit({ repoRoot, noun, name, options }) : feOwner({ repoRoot, name, options });

package/scaffold/app.d.mts

@@ -160,8 +160,8 @@ export declare const PARTIAL_VARIABLES: any;
  * The be files a generator writes when it first needs them, never the starter, so a fresh app carries no file and no export that
  * nothing reads (R25). In both editions: the entity bases of platform/database (abstract.entity.ts, BE-PERSISTENCE-3), written by
  * the first table whose entity extends them, since no starter table has both timestamps. In lite also: the cli's runners, the in-order
- * relay, and the raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only
- * the table, queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ * relay, and the sql tag of platform/database, which only the table, queue, jobs and webhook capabilities call; a fresh app reads and
+ * writes through entities and, for the account doors of its sign-in, the database-function call of database.client.ts (R334).
  */
 export declare const ENTITY_BASE_FILE = "src/modules/platform/database/abstract.entity.ts";
 /**

package/scaffold/app.mjs

@@ -18,7 +18,7 @@ import { spawnSync } from 'node:child_process';
 import { loadSlotManifest, resolveAppDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { HARNESS_PACKAGE, canonPins } from '../runtime/scripts/hfs/canon-pins.mjs';
-import { TEMPLATES_DIR, appSource, imageFiles, render, renderTargets, writeTargets } from '../sync/index.mjs';
+import { TEMPLATES_DIR, appSource, imageFiles, render, renderTargets, settleSource, writeTargets } from '../sync/index.mjs';
 import { ScaffoldError } from './service.mjs';
 import { testWorldFiles } from './test-world.mjs';
 import { FE_APP_SCRIPTS, PACKAGE_MANAGER, WORKSPACES, feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
@@ -139,7 +139,7 @@ const LITE_STARTER_SIDES = Object.freeze({
 const STARTER_DEPENDENCIES = Object.freeze({
     dependencies: {
         '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
-        '@nestjs/platform-express': null, '@nestjs/typeorm': null, 'nest-commander': null, pg: null, graphql: null,
+        '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@starci/nest-kit': null, 'nest-commander': null, pg: null, graphql: null,
         'class-transformer': null, 'class-validator': null, 'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, undici: null, zod: null,
     },
     devDependencies: {
@@ -158,15 +158,14 @@ const STARTER_DEPENDENCIES = Object.freeze({
 const LITE_STARTER_DEPENDENCIES = Object.freeze({
     dependencies: {
         '@apollo/server': null, '@nestjs/apollo': null, '@nestjs/common': null, '@nestjs/core': null, '@nestjs/cqrs': null, '@nestjs/graphql': null,
-        '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@nestjs/passport': null, passport: null, 'passport-google-oauth20': null, 'passport-local': null,
-        '@aws-sdk/client-s3': null, '@aws-sdk/s3-request-presigner': null, bcryptjs: null,
-        'class-transformer': null, 'class-validator': null, graphql: null, jose: null, pg: null,
+        '@nestjs/platform-express': null, '@nestjs/typeorm': null, '@starci/auth': null, '@starci/mail': null, '@starci/nest-kit': null, '@starci/object-storage': null,
+        'class-transformer': null, 'class-validator': null, graphql: null, pg: null,
         'reflect-metadata': null, rxjs: null, tslib: null, typeorm: null, undici: null, zod: null,
     },
     devDependencies: {
         turbo: null, '@nestjs/testing': null, '@starci/eslint-canon-be': null, '@starci/eslint-canon-fe': null,
         '@starci/jest-preset': null, '@starci/prettier-config': null, '@starci/stylelint-canon': null, '@starci/tsconfig': null, 'starci-harness': null, '@tailwindcss/postcss': null,
-        '@types/express': null, '@types/jest': null, '@types/node': null, '@types/passport-google-oauth20': null, '@types/passport-local': null, '@types/react': null, '@types/react-dom': null,
+        '@types/express': null, '@types/jest': null, '@types/node': null, '@types/react': null, '@types/react-dom': null,
         eslint: null, 'eslint-plugin-react-hooks': null, husky: null, jest: null, 'postcss-value-parser': null, prettier: null,
         stylelint: null, tailwindcss: null, 'ts-jest': null, 'ts-node-dev': null, 'tsc-alias': null,
         'tsconfig-paths': null, typescript: null,
@@ -183,22 +182,22 @@ const FE_APP_DEPENDENCIES = Object.freeze({
     '@heroui/react': null, '@heroui/styles': null, '@starci/grammar': null, '@xyflow/react': null, 'react-aria-components': null, next: null, 'next-intl': null, react: null, 'react-dom': null,
 });
 /**
- * The lite fe workspace: the same base without the shared packages, plus server-only for its own next-intl request config. It
- * holds no identity SDK: modules/auth talks only to the app's own back-end auth doors.
+ * The lite fe workspace: the same base without the shared packages (its next-intl stack is @starci/next-i18n's, a core package of the
+ * fe stack). It holds no identity SDK: modules/auth talks only to the app's own back-end auth doors.
  */
 const LITE_FE_APP_DEPENDENCIES = Object.freeze({
-    '@heroicons/react': null, '@heroui/react': null, '@heroui/styles': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'react-aria-components': null,
-    next: null, 'next-intl': null, react: null, 'react-dom': null, 'server-only': null,
+    '@heroicons/react': null, '@heroui/react': null, '@heroui/styles': null, '@starci/auth': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'react-aria-components': null,
+    next: null, 'next-intl': null, react: null, 'react-dom': null,
 });
 /**
  * The shared fe workspace packages of the starter, fe/packages/<project>-<name> named @<project>/<name>: each one's exported
  * subpaths (built to dist) and the runtime dependencies its own source imports. ui holds the drawings both apps mount; i18n the
- * next-intl stack (the entry, a server module: createAppI18n; ./proxy, the locale negotiation the apps' proxy.ts re-exports;
- * ./routing, client-safe: the default locale a client boundary reads).
+ * product's description of its languages over @starci/next-i18n (the entry, a server module: createAppI18n; ./proxy, the locale
+ * negotiation the apps' proxy.ts re-exports; ./routing, client-safe: the description and the default locale a client boundary reads).
  */
 const FE_PACKAGES = Object.freeze({
     ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'react-aria-components': null, 'next-intl': null, react: null, 'react-dom': null } },
-    i18n: { exports: ['.', './proxy', './routing'], dependencies: { next: null, 'next-intl': null, 'server-only': null } },
+    i18n: { exports: ['.', './proxy', './routing'], dependencies: { '@starci/next-i18n': null, next: null, 'server-only': null } },
 });
 /** The scripts of every fe package workspace: tsc builds it to dist and type-checks it. */
 const PACKAGE_WORKSPACE_SCRIPTS = Object.freeze({ build: 'tsc -p tsconfig.build.json', typecheck: 'tsc --noEmit -p tsconfig.json' });
@@ -334,15 +333,13 @@ const LITE_APP_REUSED = new Set(['.editorconfig', '.gitattributes', '.nvmrc']);
  * The be files a generator writes when it first needs them, never the starter, so a fresh app carries no file and no export that
  * nothing reads (R25). In both editions: the entity bases of platform/database (abstract.entity.ts, BE-PERSISTENCE-3), written by
  * the first table whose entity extends them, since no starter table has both timestamps. In lite also: the cli's runners, the in-order
- * relay, and the raw SQL helpers of platform/database (the sql tag, and the database-function call statement with its spec), which only
- * the table, queue, jobs and webhook capabilities call; a fresh app reads and writes through entities alone (R334).
+ * relay, and the sql tag of platform/database, which only the table, queue, jobs and webhook capabilities call; a fresh app reads and
+ * writes through entities and, for the account doors of its sign-in, the database-function call of database.client.ts (R334).
  */
 export const ENTITY_BASE_FILE = 'src/modules/platform/database/abstract.entity.ts';
 const DEFERRED_GENERATOR_FILES = new Set([ENTITY_BASE_FILE]);
 const LITE_DEFERRED_GENERATOR_FILES = new Set([
     ...DEFERRED_GENERATOR_FILES,
-    'src/modules/platform/database/database.client.ts',
-    'src/modules/platform/database/database.client.spec.ts',
     'src/modules/platform/database/database.sql.ts',
     'src/modules/platform/database/migration-runner.service.ts',
     'src/modules/platform/database/seed-runner.service.ts',
@@ -656,7 +653,8 @@ export function scaffoldApp({ name, into, presets, harness, edition = 'full', re
     try {
         for (const file of files)
             writes.write(file.path, file.content);
-        const targets = renderTargets(declaration, presets, { manifest, source: appSource(root) });
+        const source = appSource(root);
+        const targets = renderTargets(declaration, presets, { manifest, source: settleSource(source, renderTargets(declaration, presets, { manifest, source })) });
         for (const target of targets)
             writes.claim(target.path);
         writeTargets(root, targets);

package/scaffold/lite-exports.mjs

@@ -59,20 +59,13 @@ const REGISTRATIONS = Object.freeze({
             names: ["sql"],
             beforeSource: "./errors/database.error",
         },
-        {
-            // The outbox write and the relay call the queue functions of their migration (R334).
-            file: "be/src/modules/platform/database/index.ts",
-            source: "./database.client",
-            names: ["callDbFunction"],
-            beforeSource: "./primary.decorators",
-        },
     ],
     // The jobs capability (add job, the fenced-job pattern): its tick takes a transaction-scoped lock before it claims the minute (R335).
     jobs: [
         {
             file: "be/src/modules/platform/database/index.ts",
             source: "./database.client",
-            names: ["advisoryXactLock", "callDbFunction"],
+            names: ["advisoryXactLock"],
             beforeSource: "./primary.decorators",
         },
     ],
@@ -83,13 +76,6 @@ const REGISTRATIONS = Object.freeze({
             names: ["BATCH_ROWS", "sql"],
             beforeSource: "./errors/database.error",
         },
-        {
-            // The inbox claim and the lite event bus call the functions of their migration (R334).
-            file: "be/src/modules/platform/database/index.ts",
-            source: "./database.client",
-            names: ["callDbFunction"],
-            beforeSource: "./primary.decorators",
-        },
         {
             // PRIMARY_ENTITY_MANAGER: the token the inbox service's unit spec provides its EntityManager double under.
             file: "be/src/modules/platform/database/index.ts",

package/scaffold/module-registry.d.mts

@@ -0,0 +1,19 @@
+/** The folder name prefix of a module package. */
+export declare const MODULE_PREFIX = "module-";
+/** The package that lists every module package. */
+export declare const REGISTRY_DIR = "packages/modules";
+/** The product's agent SDK package folder every module builds on. */
+export declare const SDK_DIR = "packages/agent-sdk";
+/** A file of the registry package: its app-relative path and its content. */
+export interface RegistryFile {
+    readonly path: string;
+    readonly content: string;
+}
+/** `loyalty-points` as the UPPER_SNAKE prefix of the constants a module exports. */
+export declare const upperOf: (name: string) => string;
+/** The module names under `packages/` of the app at `root` (a folder module-<name> holding a package.json), sorted. */
+export declare function moduleNames(root: string): string[];
+/** The files of the registry package for `names` (empty when no module exists: the package is then absent). */
+export declare function registryFiles(project: string, names: readonly string[]): RegistryFile[];
+/** The PascalCase label of a module, for the messages that name it. */
+export declare const labelOf: (name: string) => string;

package/scaffold/module-registry.mjs

@@ -0,0 +1,84 @@
+// module-registry.mts - the module packages of an app (packages/module-<name>) and the registry package (packages/modules) that lists them.
+//
+// The registry is managed: its manifests and its three source files are rendered from the module list, by `starci app add|remove module` and by
+// `starci app sync` (the same function), so a hand edit is drift. A module package is written once by `add module` and is the product's from then on.
+import fs from 'node:fs';
+import path from 'node:path';
+import { byCodeUnit } from '../report/order.mjs';
+import { pascalOf } from './service.mjs';
+/** The folder name prefix of a module package. */
+export const MODULE_PREFIX = 'module-';
+/** The package that lists every module package. */
+export const REGISTRY_DIR = 'packages/modules';
+/** The product's agent SDK package folder every module builds on. */
+export const SDK_DIR = 'packages/agent-sdk';
+const HEADER = '// Generated by starci app sync (module registry). Do not edit: run "npx starci app sync --execute".';
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** `loyalty-points` as the UPPER_SNAKE prefix of the constants a module exports. */
+export const upperOf = (name) => name.replace(/-/g, '_').toUpperCase();
+/** The module names under `packages/` of the app at `root` (a folder module-<name> holding a package.json), sorted. */
+export function moduleNames(root) {
+    const folder = path.join(root, 'packages');
+    if (!fs.existsSync(folder))
+        return [];
+    return fs.readdirSync(folder, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith(MODULE_PREFIX) && fs.existsSync(path.join(folder, entry.name, 'package.json')))
+        .map((entry) => entry.name.slice(MODULE_PREFIX.length))
+        .sort(byCodeUnit);
+}
+/** The exports map of the registry and of a module: the React-free halves and, for a module, its Grammar workbench. */
+const registryExports = () => ({
+    '.': { types: './dist/index.d.ts', default: './dist/index.js' },
+    './template': { types: './dist/template/index.d.ts', default: './dist/template/index.js' },
+    './manifest': { types: './dist/manifest/index.d.ts', default: './dist/manifest/index.js' },
+});
+/** The files of the registry package for `names` (empty when no module exists: the package is then absent). */
+export function registryFiles(project, names) {
+    if (names.length === 0)
+        return [];
+    const sorted = [...names].sort(byCodeUnit);
+    const sdk = `@${project}/agent-sdk`;
+    const module = (name) => `@${project}/${MODULE_PREFIX}${name}`;
+    const serverImports = sorted.map((name) => `import { ${upperOf(name)}_SERVER } from "${module(name)}/template"`).join('\n');
+    const workbenchImports = sorted.map((name) => `import { ${upperOf(name)}_WORKBENCH } from "${module(name)}/manifest"`).join('\n');
+    const dependencies = Object.fromEntries([[sdk, '*'], ...sorted.map((name) => [module(name), '*'])].sort(([a], [b]) => byCodeUnit(a, b)));
+    return [
+        {
+            path: `${REGISTRY_DIR}/package.json`,
+            content: json({
+                name: `@${project}/modules`,
+                version: '0.0.0',
+                private: true,
+                description: 'The one list of the product modules built on the agent SDK, all React-free: ./template (every module\'s server half, for the back end) and ./manifest (every workbench declaration and the spec registry they assemble).',
+                exports: registryExports(),
+                scripts: { build: 'tsc -p tsconfig.build.json', typecheck: 'tsc --noEmit --pretty false' },
+                dependencies,
+            }),
+        },
+        {
+            path: `${REGISTRY_DIR}/tsconfig.json`,
+            content: json({ extends: '@starci/tsconfig/next.json', compilerOptions: { incremental: false, types: [] }, include: ['src/**/*.ts'], exclude: ['node_modules', 'dist'] }),
+        },
+        {
+            path: `${REGISTRY_DIR}/tsconfig.build.json`,
+            content: json({
+                extends: './tsconfig.json',
+                compilerOptions: { rootDir: 'src', outDir: 'dist', noEmit: false, declaration: true, module: 'node16', moduleResolution: 'node16' },
+            }),
+        },
+        {
+            path: `${REGISTRY_DIR}/src/index.ts`,
+            content: `${HEADER}\nimport { MODULE_SERVERS } from "./template"\n\n/** The keys of every module this registry lists, for a host that checks its own wiring against it. */\nexport const REGISTERED_MODULE_KEYS: ReadonlyArray<string> = MODULE_SERVERS.map((module) => module.key)\n`,
+        },
+        {
+            path: `${REGISTRY_DIR}/src/template/index.ts`,
+            content: `${HEADER}\nimport type { ModuleServer } from "${sdk}/module"\n${serverImports}\n\n/** The server half of every module built on the SDK; the back end reads nothing else of a module. */\nexport const MODULE_SERVERS: ReadonlyArray<ModuleServer> = [${sorted.map((name) => `${upperOf(name)}_SERVER`).join(', ')}]\n`,
+        },
+        {
+            path: `${REGISTRY_DIR}/src/manifest/index.ts`,
+            content: `${HEADER}\nimport { specRegistryFrom } from "${sdk}/workbench/contract"\nimport type { WorkbenchDeclaration, WorkbenchSpecRegistry } from "${sdk}/workbench/contract"\n${workbenchImports}\n\n/** The workbench declaration of every module built on the SDK; the front end pairs each with how it draws. */\nexport const MODULE_WORKBENCHES: ReadonlyArray<WorkbenchDeclaration> = [${sorted.map((name) => `${upperOf(name)}_WORKBENCH`).join(', ')}]\n\n/** Everything a stored spec may name: the SDK's blocks and each module's exposed blocks, reads and actions. */\nexport const SPEC_REGISTRY: WorkbenchSpecRegistry = specRegistryFrom(MODULE_WORKBENCHES)\n`,
+        },
+    ];
+}
+/** The PascalCase label of a module, for the messages that name it. */
+export const labelOf = (name) => pascalOf(name);

package/scripts/sync-bundles.d.mts

@@ -29,3 +29,11 @@ export declare function syncBundles(options: {
     readonly check: boolean;
     readonly packages?: readonly string[];
 }): SyncResult;
+/** The harness runtime layers whose recipe hfs ships for `starci app stack up` (stack/runtime-layers.mts): the folder name under images/ of the harness repository. */
+export declare const layerRecipes: readonly ["openclaw-runtime"];
+/** Syncs (or judges) the shipped copy stack/images/<layer>/ of each recipe against the owner, `images/<layer>/` of the harness repository. */
+export declare function syncLayerRecipes(options: {
+    readonly imagesDir: string;
+    readonly shippedDir: string;
+    readonly check: boolean;
+}): SyncResult;

package/src/main.mjs

@@ -101,6 +101,7 @@ import { emitContractsAsync } from '../emit/contracts.mjs';
 import { ScaffoldError, newService, newSpec } from '../scaffold/service.mjs';
 import { EditionRefusal } from '../scaffold/edition-gate.mjs';
 import { addKind } from '../scaffold/add.mjs';
+import { removeModule } from '../scaffold/add-module.mjs';
 import { scaffoldApp } from '../scaffold/app.mjs';
 import { newImages } from '../scaffold/image.mjs';
 import { cachedLinters, eslintRepository, runLinter as nativeLinter } from '../lint/run.mjs';
@@ -140,7 +141,7 @@ const listFlag = (opts, flag) => { const given = opts[flag]; return Array.isArra
 /** An argument the parser refuses (an unknown flag, a missing value, a form a verb does not take): the one error `main` follows with the usage. */
 export class UsageError extends Error {
 }
-export const VERBS = Object.freeze(['scaffold', 'add', 'sync', 'check', 'upgrade', 'stack', 'world', 'release', 'slot', 'emit', 'secret', 'ci', 'db', 'coverage', 'codemod']);
+export const VERBS = Object.freeze(['scaffold', 'add', 'remove', 'sync', 'check', 'upgrade', 'stack', 'world', 'release', 'slot', 'emit', 'secret', 'ci', 'db', 'coverage', 'codemod']);
 const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['new', dbNewMain], ['drift', dbDriftMain]]);
 /**
  * The verbs parsed here, each with the only flags it takes ({ boolean, value, list }); a flag of another verb is refused, never ignored.
@@ -158,12 +159,13 @@ const PARSED = {
     add: {
         run: addMain, ...ADD_FLAGS, list: ['--inject'],
         forms: [
-            { operands: '<api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app|block|frame|composite|branch|leaf|page|overlay|layout> <name>', only: ADD_FLAGS },
+            { operands: '<api|webhook|realtime|saga|job|reactor|queue|projection|cli|table|app|module|block|frame|composite|branch|leaf|page|overlay|layout> <name>', only: ADD_FLAGS },
             { operands: 'service <dir> <name>', only: { list: ['--inject'] } },
             { operands: 'spec <file>.service.ts', flags: [] },
             { operands: 'image', flags: [] },
         ],
     },
+    remove: { run: removeMain, forms: [{ operands: 'module <name>', flags: [] }] },
     check: { run: checkMain, value: ['--coverage-from', '--shard', '--side', '--out'], list: GATE_FLAGS, boolean: ['--json', '--staged', '--no-cache', '--fix'], edition: true, forms: [{ only: { boolean: ['--json', '--no-cache', '--fix'], list: GATE_FLAGS, value: ['--coverage-from', '--shard', '--side', '--out'] } }, { only: { boolean: ['--staged'] }, edition: false }] },
     slot: { run: slotMain, boolean: ['--json'], forms: [{ operands: '<path>' }] },
     emit: { run: emitMain, forms: [{}] },
@@ -204,6 +206,11 @@ const VERB_USAGE = {
     world: ['starci app world <up|down|status> [--stack <dir>] [--services <list>] [--k3d] [--force] [--json] [--edition full|lite]'],
     stack: [
         ...STACK_ACTIONS.map((action) => line(`starci app stack ${action}`, STACK_OPERANDS[action], STACK_READ_ONLY.includes(action) ? flagUsage('--env', { value: true }) : '--env <env>', STACK_FLAGS[action].map((flag) => flagUsage(flag, { value: STACK_VALUE.has(flag), repeat: STACK_REPEAT.has(flag) })), '[--json]')),
+        // The dev actions of a docker-compose environment (stack/local-cli.mts); prepare, status and verify above answer them too.
+        'starci app stack doctor --env <env> [--json]',
+        'starci app stack up --env <env> [--execute] [--timeout <seconds>] [--json]',
+        'starci app stack down --env <env> [--execute] [--json]',
+        'starci app stack logs --env <env> --service <name> [--lines <n>] [--json]',
     ],
     release: Object.entries(RELEASE_FLAGS).map(([action, spec]) => line(`starci app release ${action}`, specUsage(spec))),
     secret: SECRET_VERBS.map((verb) => line(`starci app secret ${verb}`, secretUsage(verb))),
@@ -680,6 +687,20 @@ function addMain(opts, { cwd: repoRoot, stdout: out }) {
         out(`starci app add ${noun}: registered patterns ${registered.patterns.join(', ')}${kinds}\n`);
     return 0;
 }
+/** `remove module <name>`: deletes the module package and its registrations and re-renders the registry. */
+function removeMain(opts, { cwd: repoRoot, stdout: out }) {
+    const [noun, name, ...extra] = opts.positional;
+    if (noun !== 'module' || !name || extra.length)
+        throw new UsageError('starci app remove takes `module <name>`');
+    const { removed, updated, created } = removeModule({ root: repoRoot, name });
+    for (const file of removed)
+        out(`removed ${file}
+`);
+    for (const file of [...updated, ...created])
+        out(`updated ${file}
+`);
+    return 0;
+}
 async function scaffoldMain(opts, { cwd, harness, edition = 'full', presets, lock, stdout: out }) {
     const [name, ...extra] = opts.positional;
     const registryVisibility = valueFlag(opts, 'registry-visibility');

package/stack/cli.mjs

@@ -18,6 +18,7 @@ import { withDockerTransport } from './docker-transport.mjs';
 import { StackError, EXIT, refusal } from './errors.mjs';
 import { parseTargetBinding, bindStackTarget, nativeToolEnvironment } from './target-binding.mjs';
 import { oneCommand, prepareUrgentRelease } from './urgent-release.mjs';
+import { isLocalEnvironment, isLocalOnly, isLocalShared, runLocal } from './local-cli.mjs';
 /** The actions that drive the docker CLI of the operator machine (pointed at the manager by docker-transport.mjs when the key is sealed). */
 const DOCKER_ACTIONS = new Set(['deploy', 'accept', 'converge', 'verify', 'rollback', 'prune', 'status']);
 export const ACTIONS = Object.freeze(['prepare', 'connect', 'disconnect', 'build-args', 'render', 'deploy', 'converge', 'verify', 'rollback', 'prune', 'backup', 'jobs', 'task', 'ingress', 'retire', 'build', 'accept', 'status', 'ci-key']);
@@ -185,8 +186,12 @@ export async function stackMain(argv, io = {}) {
     const ctx = stackContext(io);
     try {
         const action = argv[0];
+        if (isLocalOnly(action))
+            return await runLocal(ctx, action, argv.slice(1), io.localDeps);
         if (!isAction(action))
-            throw refusal('STACK_USAGE', `starci app stack takes ${[...ACTIONS, 'up', 'down', 'status'].join(', ')}`);
+            throw refusal('STACK_USAGE', `starci app stack takes ${[...ACTIONS, 'doctor', 'up', 'down', 'logs'].join(', ')}`);
+        if (isLocalShared(action) && argv.includes('--env') && isLocalEnvironment(ctx.cwd, String(argv[argv.indexOf('--env') + 1])))
+            return await runLocal(ctx, action, argv.slice(1), io.localDeps);
         const { flags, positional } = parseFlags(action, argv.slice(1));
         if (flags.env === undefined && !READ_ONLY.includes(action))
             throw refusal('STACK_USAGE', `stack ${action} has an effect: name its environment with --env <env> (only ${READ_ONLY.join(', ')} default to production)`);

package/stack/context.d.mts

@@ -47,6 +47,16 @@ export interface PipeResult {
     sink: number;
     stderr: string;
 }
+/** One heavy command the dev verbs run (`npm ci`, a compose build or up): admitted by the harness's heavy-command governor when it hands one in. */
+export interface HeavyRequest {
+    kind: 'install' | 'build';
+    label: string;
+    cwd: string;
+    argv: string[];
+    env: NodeJS.ProcessEnv;
+}
+/** The governed runner: waits for a slot of the host-wide semaphore, runs the argv without a shell and returns its result. */
+export type HeavyRun = (request: HeavyRequest) => Promise<RunResult>;
 /** The secret seam: decrypts the app's sops files. */
 export interface Sops {
     decrypt(file: string, format?: string): Record<string, string>;
@@ -82,6 +92,9 @@ export interface StackIo {
         role?: string | undefined;
     } | undefined;
     importer?: ((file: string) => Promise<Record<string, unknown>>) | undefined;
+    heavy?: HeavyRun | undefined;
+    /** The seams of the dev verbs a spec replaces (stack/local-run.mjs LocalDeps). */
+    localDeps?: import('./local-run.mjs').LocalDeps | undefined;
 }
 /** The context of one stack invocation (see stackContext). */
 export interface StackContext {
@@ -98,6 +111,8 @@ export interface StackContext {
     readonly fetch: typeof fetch;
     readonly pipe: (source: PipeEnd, sink: PipeEnd) => Promise<PipeResult>;
     readonly sops: Sops;
+    /** The governed runner of heavy commands (the harness CLI hands it in); absent, a dev verb runs them directly. */
+    readonly heavy?: HeavyRun | undefined;
     /** The command-owned SSH connection, set by the Docker transport (docker-transport.mjs). */
     readonly stackSsh?: SshConnection | undefined;
 }

package/stack/context.mjs

@@ -74,6 +74,7 @@ export function stackContext(io = {}) {
         stderr: io.stderr ?? ((text) => process.stderr.write(text)),
         fetch: io.fetch ?? globalThis.fetch,
         pipe: io.pipe ?? realPipe,
+        heavy: io.heavy,
         /** The secret seam: the app's own sops/age tools, created on first use so verbs that open no custody never need them. */
         get sops() {
             const opened = sops ?? io.openSops?.() ?? defaultSops(env, cwd, io.platform ?? process.platform, undefined, io.hostIdentity ?? null);

package/stack/images/openclaw-runtime/Dockerfile

@@ -0,0 +1,18 @@
+# StarCi OpenClaw runtime layer: the harness-pinned source-built fork (images/openclaw, sources.json) plus the generic gateway wrapper.
+# An app image does `FROM ghcr.io/starci183/openclaw-runtime@sha256:...` and only COPYs its own plugins into /opt/starci/plugins/<name>/;
+# it carries no wrapper code (images/README.md "The OpenClaw runtime layer"). The base below is the recorded `published.reference` of the
+# `openclaw` entry of sources.json; a new fork build raises it here in the same change.
+FROM ghcr.io/starci183/openclaw:2026.10.10-beta.5-starci.1@sha256:0770c1da11ec4a46607ec16957ac3cff68d05db4a287f59f0e1d0e76de980ff8
+
+USER root
+# The wrapper is root-owned and not writable by the runtime user; the plugin directory is root-owned and world-readable, so a plugin an
+# app copies in cannot be rewritten by the gateway it runs inside.
+COPY --chmod=0555 entrypoint.sh /opt/starci/entrypoint.sh
+COPY --chmod=0444 openclaw-init.mjs openclaw-relay.mjs /opt/starci/
+RUN mkdir -p /opt/starci/plugins \
+    && chown -R root:root /opt/starci \
+    && chmod 0755 /opt/starci /opt/starci/plugins
+
+USER node
+ENV STARCI_PLUGINS_DIR=/opt/starci/plugins
+ENTRYPOINT ["tini", "-s", "--", "sh", "/opt/starci/entrypoint.sh"]

package/stack/images/openclaw-runtime/entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Entrypoint of the StarCi OpenClaw runtime layer (/opt/starci/entrypoint.sh).
+#
+# 1. The OpenClaw image has no `<NAME>_FILE` support, so every secret named in STARCI_SECRETS (space separated; OPENCLAW_GATEWAY_TOKEN is always
+#    read) is exported from /run/secrets/<NAME> into THIS process tree only: no env file on the host, no value in the service specification.
+# 2. openclaw-init.mjs merges the gateway settings into openclaw.json (idempotent; other keys, agents and plugins are kept) and enables the plugins
+#    found under STARCI_PLUGINS_DIR.
+# 3. openclaw-relay.mjs listens on the overlay address and forwards to the loopback-only gateway: the gateway honours the scopes a client
+#    declares only for a loopback peer using the shared secret, so clients connect to the relay (OPENCLAW_RELAY_PORT, default 18790).
+set -eu
+
+for name in OPENCLAW_GATEWAY_TOKEN ${STARCI_SECRETS:-}; do
+  file="/run/secrets/$name"
+  if [ -r "$file" ]; then
+    value="$(cat "$file")"
+    export "$name=$value"
+  fi
+done
+: "${OPENCLAW_GATEWAY_TOKEN:?the secret OPENCLAW_GATEWAY_TOKEN is not granted to this service}"
+
+OPENCLAW_GATEWAY_TOKEN_FILE=/run/secrets/OPENCLAW_GATEWAY_TOKEN node /opt/starci/openclaw-init.mjs
+node /opt/starci/openclaw-relay.mjs &
+exec node openclaw.mjs gateway