genesis-compiler 1.2.5 → 1.2.7

package/src/index/verification.js

@@ -6,6 +6,9 @@ import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 import { readStack } from './stack.js';
 import { inspectWorkspaceSetupForStack } from './workspace-setup.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+
+const DEFAULT_FINITE_COMMAND_TIMEOUT_MS = 30 * 60 * 1_000;
 
 async function emit(onEvent, event) {
   try { await onEvent?.(event); } catch { /* Progress observers do not control verification. */ }
@@ -16,12 +19,16 @@ export async function verifyProject({
   onEvent,
   processRunner = runProcess,
   projectRoot,
+  signal,
+  stackPackages = [],
+  timeoutMs = DEFAULT_FINITE_COMMAND_TIMEOUT_MS,
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const workspaceSetup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
   if (workspaceSetup.status === 'blocked') {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'blocked',
       summary: workspaceSetup.diagnostics.map(({ message }) => message).join(' '),
       commands: [],
@@ -33,6 +40,7 @@ export async function verifyProject({
   );
   if (waiting.length > 0) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'unconfigured',
       summary: waiting.map(({ message }) => message).join(' '),
       commands: [],
@@ -49,6 +57,7 @@ export async function verifyProject({
   });
   if (missing.length > 0) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'blocked',
       summary: missing.map(({ message }) => message).join(' '),
       commands: [],
@@ -57,6 +66,7 @@ export async function verifyProject({
   }
   if (stack.commands.length === 0) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'unconfigured',
       summary: 'The selected Stack declares no verification commands.',
       commands: [],
@@ -79,6 +89,8 @@ export async function verifyProject({
         env: resolvedEnvironment,
         maxBytes: 32 * 1024 * 1024,
         code: 'VERIFICATION_FAILED',
+        signal,
+        timeoutMs,
       });
       await emit(onEvent, {
         type: 'genesis.verification',
@@ -90,6 +102,7 @@ export async function verifyProject({
     }
     const evidence = await writeVerification({ projectRoot: root, stack });
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'passed',
       summary: `Passed ${commands.length} declared verification command${commands.length === 1 ? '' : 's'}.`,
       commands,
@@ -98,6 +111,7 @@ export async function verifyProject({
     };
   } catch (error) {
     return {
+      contract: GENESIS_CONTRACTS.verification,
       status: 'failed',
       summary: error.message,
       commands: [],

package/src/index/workspace-setup.js

@@ -7,6 +7,9 @@ import { runProcess } from './process.js';
 import { readStack } from './stack.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
+import { GENESIS_CONTRACTS } from './contracts.js';
+
+const DEFAULT_FINITE_COMMAND_TIMEOUT_MS = 30 * 60 * 1_000;
 
 async function emit(onEvent, event) {
   try { await onEvent?.(event); } catch { /* Progress observers do not control preparation. */ }
@@ -54,6 +57,7 @@ export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }
     ? sha256(stableJson({ version: 1, steps: applicableSteps }))
     : '';
   return {
+    contract: GENESIS_CONTRACTS.workspaceSetup,
     status,
     stackHash: stack.identityHash,
     recipeHash,
@@ -70,9 +74,10 @@ export async function inspectWorkspaceSetupForStack({ projectRoot: root, stack }
 /** Read the Stack's workspace preparation recipe without executing it. */
 export async function inspectProjectWorkspaceSetup({
   projectRoot,
+  stackPackages = [],
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   return inspectWorkspaceSetupForStack({ projectRoot: root, stack });
 }
 
@@ -82,9 +87,12 @@ export async function prepareProjectWorkspace({
   onEvent,
   processRunner = runProcess,
   projectRoot,
+  signal,
+  stackPackages = [],
+  timeoutMs = DEFAULT_FINITE_COMMAND_TIMEOUT_MS,
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
-  const stack = await readStack(root);
+  const stack = await readStack(root, { stackPackages });
   const setup = await inspectWorkspaceSetupForStack({ projectRoot: root, stack });
   if (setup.status !== 'ready') {
     const summary = setup.diagnostics.map(({ message }) => message).join(' ')
@@ -114,6 +122,8 @@ export async function prepareProjectWorkspace({
         env: resolvedEnvironment,
         maxBytes: 32 * 1024 * 1024,
         code: 'WORKSPACE_PREPARATION_FAILED',
+        signal,
+        timeoutMs,
       });
       commands.push({
         label: step.label,

package/src/index.js

@@ -9,7 +9,7 @@ import { installCodexPlugin } from './index/codex-plugin.js';
 import { inspectProjectEnvironment } from './index/environment-files.js';
 import { inspectProjectDeployment } from './index/deployment.js';
 import { inspectProjectLaunch } from './index/launch.js';
-import { listBuiltinStackPieces } from './index/stack-catalog.js';
+import { listStackCatalogPieces } from './index/stack-catalog.js';
 import { addStackPieces } from './index/stack.js';
 import { verifyProject } from './index/verification.js';
 import {
@@ -17,6 +17,8 @@ import {
   prepareProjectWorkspace,
 } from './index/workspace-setup.js';
 
+export { GENESIS_CONTRACTS } from './index/contracts.js';
+
 function withIndexResult(result, index) {
   const changedFiles = [...new Set([...result.changedFiles, ...index.changedFiles])].sort();
   const refreshedOnly = result.status === 'unchanged' && index.changedFiles.length > 0;
@@ -29,21 +31,26 @@ function withIndexResult(result, index) {
   };
 }
 
-async function initializeWithIndex(projectRoot) {
-  const initialized = await initializeProject({ projectRoot });
-  const index = await buildProjectIndex({ projectRoot });
+async function initializeWithIndex(projectRoot, stackPackages = []) {
+  const initialized = await initializeProject({ projectRoot, stackPackages });
+  const index = await buildProjectIndex({ projectRoot, stackPackages });
   return withIndexResult(initialized, index);
 }
 
-export function initialize({ projectRoot = process.cwd() } = {}) {
-  return initializeWithIndex(projectRoot);
+export function initialize({ projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  return initializeWithIndex(projectRoot, stackPackages);
 }
 
-export async function adoptProject({ projectRoot = process.cwd(), request = '' } = {}) {
-  const initialized = await initializeWithIndex(projectRoot);
+export async function adoptProject({
+  projectRoot = process.cwd(),
+  request = '',
+  stackPackages = [],
+} = {}) {
+  const initialized = await initializeWithIndex(projectRoot, stackPackages);
   const description = await generateProjectPrompt({
     projectRoot,
     request,
+    stackPackages,
     task: 'adopt',
   });
   return {
@@ -62,15 +69,15 @@ export function installCodex({ environment = process.env } = {}) {
   return installCodexPlugin({ environment });
 }
 
-export async function addStack({ pieces, projectRoot = process.cwd() } = {}) {
+export async function addStack({ pieces, projectRoot = process.cwd(), stackPackages = [] } = {}) {
   const root = path.resolve(projectRoot);
-  const selected = await addStackPieces({ pieces, projectRoot: root });
-  const index = await buildProjectIndex({ projectRoot: root });
+  const selected = await addStackPieces({ pieces, projectRoot: root, stackPackages });
+  const index = await buildProjectIndex({ projectRoot: root, stackPackages });
   return withIndexResult(selected, index);
 }
 
-export function listStackPieces() {
-  return listBuiltinStackPieces();
+export function listStackPieces(options = {}) {
+  return listStackCatalogPieces(options);
 }
 
 export function inspectLaunch(options) {
@@ -97,12 +104,17 @@ export function generatePrompt(options) {
   return generateProjectPrompt(options);
 }
 
-export function getContext({ paths, projectRoot = process.cwd() } = {}) {
-  return contextForProjectPaths({ paths, projectRoot });
+export function getContext({ paths, projectRoot = process.cwd(), stackPackages = [] } = {}) {
+  return contextForProjectPaths({ paths, projectRoot, stackPackages });
 }
 
-export function indexCodebase({ projectRoot = process.cwd(), queries = [], write = true } = {}) {
-  return buildProjectIndex({ projectRoot, queries, write });
+export function indexCodebase({
+  projectRoot = process.cwd(),
+  queries = [],
+  stackPackages = [],
+  write = true,
+} = {}) {
+  return buildProjectIndex({ projectRoot, queries, stackPackages, write });
 }
 
 export function verify(options) {

package/stacks/pieces/cpp.md

@@ -1,34 +0,0 @@
-# Stack piece: cpp
-
-## Description
-
-C and C++ translation-unit, header, callable, ownership, build, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `cpp`
-
-## Adoption
-
-- Identify the actual build system and presets, compiler and language level,
-  package/runtime dependencies, generated-source steps, and supported build
-  configurations without substituting a preferred CMake or Meson layout.
-- Record exact configure/build/test commands and the executable argv, workdir,
-  host/port handling, HTTP readiness predicate, and signal/shutdown contract for
-  every web-service target.
-- Preserve public headers, ABI and platform assumptions. Treat databases,
-  queues, TLS material, and external service credentials as explicit Resources,
-  not implicit properties of the native binary.
-
-## Deslop
-
-- Preserve public header boundaries, ABI expectations, build configuration,
-  const correctness, lifetime ownership, and the codebase's C or C++ level.
-- Keep file-local helpers internal and near their callers. Consolidate repeated
-  allocation, cleanup, conversion, and error paths with explicit ownership.
-- Remove unused wrappers, speculative templates, duplicate overload plumbing,
-  and abstractions that obscure control flow without protecting a real boundary.

package/stacks/pieces/csharp.md

@@ -1,22 +0,0 @@
-# Stack piece: csharp
-
-## Description
-
-C# namespace, public type, dependency, lifecycle, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `csharp`
-
-## Deslop
-
-- Preserve established namespaces, public contracts, dependency injection,
-  async ownership, disposal, nullable annotations, and project conventions.
-- Keep private helpers with their owning type. Consolidate repeated mapping,
-  validation, and error translation at an existing application boundary.
-- Remove redundant service wrappers, interfaces with no useful substitution
-  boundary, and extension methods that only rename direct framework behavior.

package/stacks/pieces/go.md

@@ -1,22 +0,0 @@
-# Stack piece: go
-
-## Description
-
-Go package, exported callable, interface, concurrency, resource, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `go`
-
-## Deslop
-
-- Preserve package ownership, exported APIs, context propagation, error
-  wrapping, goroutine lifetime, and standard Go tooling conventions.
-- Keep unexported helpers close to their caller. Consolidate repeated setup,
-  validation, cleanup, and conversion only at a clear package boundary.
-- Remove unnecessary interfaces, constructor wrappers, channels, and generic
-  helpers that make direct control flow harder to follow.

package/stacks/pieces/java.md

@@ -1,22 +0,0 @@
-# Stack piece: java
-
-## Description
-
-Java package, public type, dependency, lifecycle, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `java`
-
-## Deslop
-
-- Preserve established packages, public interfaces, dependency injection,
-  lifecycle ownership, checked-error policy, and build-tool conventions.
-- Keep private helpers with their owning class. Consolidate repeated mapping,
-  validation, and resource handling at an existing service or domain boundary.
-- Remove empty facades, single-implementation abstractions, and builder or DTO
-  layers that do not protect a real public or compatibility boundary.

package/stacks/pieces/jskit-mysql.md

@@ -1,56 +0,0 @@
-# Stack piece: jskit-mysql
-
-## Description
-
-JSKIT MySQL runtime, live-schema CRUD generation, and persistence conventions.
-
-## Requires
-
-- `jskit`
-- `mysql`
-
-## Conflicts
-
-- `jskit-postgresql`
-
-## Environment defaults
-
-- Default `DB_CLIENT`: `mysql2`
-
-## Resources
-
-```json genesis-resource
-{
-  "id": "database",
-  "kind": "mysql",
-  "environmentAlternatives": [
-    {
-      "required": ["DATABASE_URL"]
-    },
-    {
-      "required": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
-      "allowEmpty": ["DB_PASSWORD"]
-    }
-  ]
-}
-```
-
-## Adoption
-
-- Confirm that the application's effective MySQL environment alternatives and
-  driver match this Resource declaration; add a project Resource contract when
-  the existing application legitimately differs.
-- Verify from source that the database preparation path discovers every
-  package-owned migration, preserves the existing ledger, orders cross-package
-  constraints safely, and invokes an app-owned idempotent seed. Do not execute
-  it during adoption.
-
-## Deslop
-
-- Use the installed JSKIT database runtime and generated resource/repository
-  seams; do not add a second client, connection factory, CRUD transport, or
-  file-persistence fallback.
-- Keep environment normalization, transactions, row mapping, and database
-  error translation at one established persistence boundary.
-- Never compete with or rewrite a generator-owned baseline migration. Preserve
-  retained migration history and data semantics.

package/stacks/pieces/jskit-postgresql.md

@@ -1,56 +0,0 @@
-# Stack piece: jskit-postgresql
-
-## Description
-
-JSKIT PostgreSQL runtime, live-schema CRUD generation, and persistence conventions.
-
-## Requires
-
-- `jskit`
-- `postgresql`
-
-## Conflicts
-
-- `jskit-mysql`
-
-## Environment defaults
-
-- Default `DB_CLIENT`: `pg`
-
-## Resources
-
-```json genesis-resource
-{
-  "id": "database",
-  "kind": "postgresql",
-  "environmentAlternatives": [
-    {
-      "required": ["DATABASE_URL"]
-    },
-    {
-      "required": ["DB_HOST", "DB_PORT", "DB_NAME", "DB_USER", "DB_PASSWORD"],
-      "allowEmpty": ["DB_PASSWORD"]
-    }
-  ]
-}
-```
-
-## Adoption
-
-- Confirm that the application's effective PostgreSQL environment alternatives
-  and driver match this Resource declaration; add a project Resource contract
-  when the existing application legitimately differs.
-- Verify from source that the database preparation path discovers every
-  package-owned migration, preserves the existing ledger, orders cross-package
-  constraints safely, and invokes an app-owned idempotent seed. Do not execute
-  it during adoption.
-
-## Deslop
-
-- Use the installed JSKIT database runtime and generated resource/repository
-  seams; do not add a second client, connection factory, CRUD transport, or
-  file-persistence fallback.
-- Keep environment normalization, transactions, row mapping, and database
-  error translation at one established persistence boundary.
-- Never compete with or rewrite a generator-owned baseline migration. Preserve
-  retained migration history and data semantics.

package/stacks/pieces/jskit.md

@@ -1,114 +0,0 @@
-# Stack piece: jskit
-
-## Description
-
-AI-first JSKIT runtime capabilities, tested source patterns, Vue surfaces, and
-application-owned composition.
-
-## Requires
-
-- `nodejs`
-
-## Skill
-
-- Package: `@jskit-ai/agent-docs`
-- Path: `skills/jskit`
-
-## Guidance
-
-- Before creating or modifying JSKIT Vue/Vuetify UI, load the installed
-  `jskit` Agent Skill and read its `references/material-3.md` completely.
-- Implement Material 3 through JSKIT patterns, shared screens, shell and
-  placement seams, app-owned theme configuration, and supported Vuetify APIs.
-- Use geometry-preserving Material skeletons for all user-visible loading;
-  never use a generic spinner or circular progress indicator, or let content
-  jump when data arrives. Actions use stable disabled/pending labels.
-- Keep resource-load and field errors in context, but route transient
-  user-command failures through JSKIT's shared non-layout-shifting action
-  feedback/snackbar path.
-
-## Adoption
-
-- Read the installed JSKIT skill's existing-application migration guidance
-  completely before editing Stack or assessing readiness.
-- Inventory the coordinated `@jskit-ai/*` package graph, application-owned
-  composition, package-owned migrations, explicit repositories/features/named
-  actions, and current client resources without running a broad package update.
-- Compare the real package scripts with JSKIT's current Workspace setup,
-  Launch, verification, and Deployment declarations. Older source needs complete
-  project-owned overrides until a separately approved port supplies the current
-  commands.
-- Inspect existing setup and database preparation for both migration discovery
-  and an app-owned idempotent seed. Never infer `db:prepare` from the selected
-  component when the script or preparation file does not exist.
-- When authenticated Preview exists, preserve the app-owned Preview identity
-  command, selectors, protocol, environment names, runtime, and timeout in the
-  project's Launch declaration. A host-saved identity name/value is not a
-  substitute for this application contract.
-- Treat generator descriptors, receipts, sync commands, legacy service
-  locators, and retired tool manifests as migration evidence only. Translate
-  live facts into current source/Stack and report remaining port work; do not
-  add compatibility readers or claim adoption performed the port.
-
-## Workspace setup
-
-- Prepare `Install dependencies` with `nodejs` when `package.json` exists: `npm` `install`
-- Prepare `Prepare database` with `nodejs` if `scripts/prepare-database.js` exists: `npm` `run` `db:prepare`
-
-## Environment files
-
-- Dotenv `.env`
-
-## City regions
-
-- Ignore `**/test/**`
-- Ignore `**/tests/**`
-- Ignore `**/__tests__/**`
-- Ignore `**/*.test.*`
-- Ignore `**/*.spec.*`
-- Match `packages` as `Packages`: `packages/**`
-- Match `source` as `Source`: `src/**`
-- Fallback `everything-else` as `Everything else`
-
-## Launch
-
-### Target `app`: Run app
-
-- Default.
-- Preferred port: `3000`
-- URL path: `/`
-- Ready when: `GET` `/api/health` returns `200`
-- Runtimes: `nodejs`
-- Serve `Develop`: `npm` `run` `develop`
-
-## Deployment
-
-- Runtimes: `nodejs`
-- Ready when: `GET` `/api/health` returns `200`
-- Prepare `Install dependencies`: `npm` `install`
-- Build `Build`: `npm` `run` `build`
-- Migrate `Prepare database`: `npm` `run` `db:prepare`
-- Serve `Start`: `npm` `start`
-
-## Deslop
-
-- For every affected JSKIT screen, load the installed `jskit` Agent Skill,
-  read `references/material-3.md`, and execute its Material 3 audit.
-- Use JSKIT patterns, packages, resources, composables, screens, and placement
-  seams instead of parallel framework plumbing.
-- Treat copied pattern source as app-owned and customizable. Adapt routes,
-  placements, and infrastructure tests coherently; when replacing a foundation
-  route, update its baseline browser coverage instead of deleting it.
-- Consolidate repeated validation, pending/error state, API access, and page
-  behavior at the shared resource or established JSKIT seam.
-- Replace transient command-error alerts that shift page content with the
-  established JSKIT action feedback/snackbar seam; preserve stable in-page
-  resource-load errors, retry states, and field validation.
-- Replace generic in-content spinners with Material skeletons that reserve the
-  final layout, and verify that loading completion does not shift content.
-- Remove pass-through wrappers and abandoned scaffold code only when doing so
-  preserves routes, placements, baseline tests, and observable behavior.
-
-## Commands
-
-- Verify `application`: `npm` `run` `verify`

package/stacks/pieces/kotlin.md

@@ -1,22 +0,0 @@
-# Stack piece: kotlin
-
-## Description
-
-Kotlin package, public callable, coroutine, nullability, build, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `kotlin`
-
-## Deslop
-
-- Preserve package visibility, nullability, coroutine ownership, public types,
-  dependency injection, and Gradle or multiplatform conventions.
-- Keep private functions near their caller. Consolidate repeated mapping,
-  validation, state, and error translation at an existing boundary.
-- Remove redundant extension functions, wrappers, sealed hierarchies, and
-  generic layers that do not make the domain or lifecycle clearer.

package/stacks/pieces/mysql.md

@@ -1,29 +0,0 @@
-# Stack piece: mysql
-
-## Description
-
-MySQL persistence and migration conventions.
-
-## Requires
-
-- Nothing.
-
-## Adoption
-
-- Identify the application's accepted connection alternatives, client/driver,
-  migration directories and ledger, transaction ownership, and the exact
-  preparation command without connecting to or mutating a database.
-- Distinguish fresh-schema creation from existing-database upgrade. Record how
-  package/application migrations are ordered and how a retained ledger prevents
-  historical migrations from rerunning.
-- Identify app-owned seed behavior and whether it is deterministic and
-  idempotent. A migration-only command is not a complete seed contract.
-
-## Deslop
-
-- Keep connection configuration, transaction ownership, and database error
-  translation at one persistence boundary.
-- Use the selected integration's client and migration lifecycle instead of
-  adding parallel connection factories or schema-management code.
-- Preserve migration history and data semantics. Deslop is not permission for
-  destructive schema changes.

package/stacks/pieces/nodejs.md

@@ -1,36 +0,0 @@
-# Stack piece: nodejs
-
-## Description
-
-Node.js package, command, module, dependency, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `javascript`
-
-## Adoption
-
-- Identify the package manager from the lockfile and preserve the existing
-  module system, supported Node.js version, package entrypoints, and executable
-  commands.
-- Record the source's real dependency installation, build, verification,
-  development, and production commands. Do not assume `npm run develop`,
-  `npm test`, or `npm start` exists merely because a current foundation uses it.
-- Identify every long-running process, its workdir, host/port handling,
-  readiness signal, and shutdown ownership before declaring Launch.
-
-## Deslop
-
-- Preserve the package's existing module system, package manager, public
-  exports, registered commands, and supported runtime.
-- Prefer direct modules and Node.js built-ins over wrappers that merely rename
-  an operation.
-- Keep single-consumer helpers private and close to their caller. Consolidate
-  repeated argument, path, serialization, error, and process-lifecycle logic
-  only when one clear shared operation exists.
-- Make subprocess, listener, timer, and cleanup ownership obvious. Remove dead
-  entrypoints and duplicate public exports instead of maintaining aliases.

package/stacks/pieces/php.md

@@ -1,23 +0,0 @@
-# Stack piece: php
-
-## Description
-
-PHP package, namespace, callable, dependency, and test conventions.
-
-## Requires
-
-- Nothing.
-
-## Indexers
-
-- `php`
-
-## Deslop
-
-- Preserve established namespaces, package boundaries, public interfaces,
-  framework lifecycle, dependency injection, and Composer conventions.
-- Keep private and protected helpers close to their owning class. Consolidate
-  repeated request, validation, mapping, and persistence behavior at the
-  existing application seam rather than adding generic utility layers.
-- Remove abandoned service wrappers, duplicated facades, and aliases that do
-  not protect a real compatibility boundary.