@basaltbytes/odoo-agentic-dev 0.1.0-beta.1

package/dist/core/database-name.js

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { Effect } from "effect";
+import { UnsafeDatabaseNameError } from "../errors/errors.js";
+export const DB_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+const MAX_DB_NAME_LENGTH = 63;
+/**
+ * Derived names are capped below PostgreSQL's 63 so the 5-char `__tpl`
+ * template suffix still fits. Explicit env overrides keep the full 63 budget
+ * (template snapshots are skipped for names longer than this — see
+ * decideResetPath in core/environment.ts).
+ */
+const DERIVED_NAME_BUDGET = 58;
+/** Default leading branch type segments dropped (once) before deriving a name. */
+export const DEFAULT_STRIP_BRANCH_PREFIXES = [
+    "feature",
+    "feat",
+    "bugfix",
+    "bug",
+    "hotfix",
+    "fix",
+    "chore",
+    "task",
+];
+export const sanitizeNamePart = (raw) => raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+const sha8 = (input) => createHash("sha256").update(input).digest("hex").slice(0, 8);
+const truncate = (name) => name.length <= DERIVED_NAME_BUDGET ? name : `${name.slice(0, 49)}_${sha8(name)}`;
+const assertSafeDatabaseName = (name) => name.length === 0 || name.length > MAX_DB_NAME_LENGTH || !DB_NAME_PATTERN.test(name)
+    ? Effect.fail(new UnsafeDatabaseNameError({ name }))
+    : Effect.succeed(name);
+export const deriveDatabaseName = (options) => {
+    if (options.envDatabase !== undefined)
+        return assertSafeDatabaseName(options.envDatabase);
+    if (options.branch !== undefined &&
+        options.sharedDatabase !== null &&
+        options.sharedBranches.includes(options.branch)) {
+        return assertSafeDatabaseName(options.sharedDatabase);
+    }
+    const seed = options.branch ?? options.worktreeName;
+    const segments = seed.split("/");
+    // strip AT MOST one leading type segment — the bash `case feature/*|fix/*)`
+    // this reproduces matches a single prefix, so feature/fix/x keeps "fix"
+    const prefixes = options.stripBranchPrefixes.map((prefix) => prefix.toLowerCase());
+    if (segments.length > 1 && prefixes.includes(segments[0].toLowerCase()))
+        segments.shift();
+    let body = sanitizeNamePart(segments.join("/"));
+    if (body.length === 0)
+        body = sanitizeNamePart(options.worktreeName);
+    // bash parity: a name that sanitizes to nothing becomes "worktree", never "<prefix>_"
+    if (body.length === 0)
+        body = "worktree";
+    const prefixed = body === options.dbPrefix || body.startsWith(`${options.dbPrefix}_`)
+        ? body
+        : `${options.dbPrefix}_${body}`;
+    return assertSafeDatabaseName(truncate(prefixed));
+};
+//# sourceMappingURL=database-name.js.map

package/dist/core/database-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-name.js","sourceRoot":"","sources":["../../src/core/database-name.ts"],"names":[],"mappings":"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"}

package/dist/core/environment.d.ts

@@ -0,0 +1,84 @@
+import type { OdooAgenticDevConfig } from "./project-recipe.js";
+/**
+ * One row of the global state registry's `environments` table (camelCase
+ * mirror of the SQL schema). Nullable columns are `T | null`, never optional,
+ * so rows survive `exactOptionalPropertyTypes` round-trips through SQLite.
+ */
+export type EnvironmentRow = {
+    readonly composeProject: string;
+    readonly projectId: string;
+    readonly databaseName: string;
+    readonly rootDir: string;
+    readonly worktreeName: string;
+    /** null when detached / not a repo */
+    readonly branch: string | null;
+    readonly odooHttpPort: number;
+    readonly shared: boolean;
+    /** ISO 8601 UTC */
+    readonly createdAt: string;
+    /** ISO 8601 UTC */
+    readonly lastUsedAt: string;
+    /** e.g. kl_feature_x__tpl */
+    readonly templateDb: string | null;
+    /** hash of (modules, withoutDemo, odoo.version, postInit) */
+    readonly templateKey: string | null;
+};
+export declare const TEMPLATE_SUFFIX = "__tpl";
+/**
+ * Longest database name that still fits `TEMPLATE_SUFFIX` within PostgreSQL's
+ * 63-char identifier limit. Derived names are truncated to this budget;
+ * explicit overrides may exceed it and then simply skip template snapshots.
+ */
+export declare const TEMPLATE_BASE_NAME_BUDGET = 58;
+export declare const templateDbName: (db: string) => string;
+/**
+ * Identity of a template snapshot: everything baked into the database by a
+ * full init (modules, demo data, Odoo version, post-init hooks). Any change
+ * here must invalidate existing snapshots.
+ */
+export declare const computeTemplateKey: (recipe: OdooAgenticDevConfig) => string;
+export type EnvStatus = "running" | "stopped" | "vanished";
+export type PruneReason = "keep" | "gone-branch" | "gone-rootdir" | "vanished" | "stale" | "shared-skipped";
+/** Filesystem/git facts about a row, gathered by the caller (IO stays there). */
+export type EnvironmentProbe = {
+    readonly rootDirExists: boolean;
+    /** null = not a repo / no branch recorded — the branch rule does not apply */
+    readonly branchExists: boolean | null;
+};
+export type ClassifiedEnvironment = {
+    readonly row: EnvironmentRow;
+    readonly status: EnvStatus;
+    readonly reason: PruneReason;
+};
+/**
+ * Pure prune/list decision. Docker is the truth for status; prune reasons are
+ * evaluated in strict priority order: shared shield, vanished stack, deleted
+ * root dir, deleted branch, staleness (only when `olderThanDays` is set).
+ * Rows with no probe entry are conservatively kept.
+ */
+export declare const classifyEnvironments: (input: {
+    readonly rows: ReadonlyArray<EnvironmentRow>;
+    readonly dockerProjects: ReadonlyArray<{
+        readonly name: string;
+        readonly running: boolean;
+    }>;
+    readonly probes: ReadonlyMap<string, EnvironmentProbe>;
+    readonly olderThanDays: number | null;
+    readonly allowShared: boolean;
+    /** ISO 8601 UTC */
+    readonly now: string;
+}) => ReadonlyArray<ClassifiedEnvironment>;
+export type ResetPath = "restore" | "full" | "full-then-snapshot";
+/**
+ * Pure reset-path decision for `reset-db`/`setup`. Snapshots are only ever
+ * planned for names within `TEMPLATE_BASE_NAME_BUDGET` — over-budget names
+ * (explicit overrides) degrade every snapshot outcome to a plain `full`.
+ */
+export declare const decideResetPath: (input: {
+    readonly row: EnvironmentRow | undefined;
+    readonly expectedKey: string;
+    readonly databaseName: string;
+    readonly noTemplate: boolean;
+    readonly refreshTemplate: boolean;
+    readonly hasOverrides: boolean;
+}) => ResetPath;

package/dist/core/environment.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+export const TEMPLATE_SUFFIX = "__tpl";
+/**
+ * Longest database name that still fits `TEMPLATE_SUFFIX` within PostgreSQL's
+ * 63-char identifier limit. Derived names are truncated to this budget;
+ * explicit overrides may exceed it and then simply skip template snapshots.
+ */
+export const TEMPLATE_BASE_NAME_BUDGET = 58;
+export const templateDbName = (db) => `${db}${TEMPLATE_SUFFIX}`;
+/**
+ * Identity of a template snapshot: everything baked into the database by a
+ * full init (modules, demo data, Odoo version, post-init hooks). Any change
+ * here must invalidate existing snapshots.
+ */
+export const computeTemplateKey = (recipe) => createHash("sha256")
+    .update(JSON.stringify([
+    recipe.database.initialModules,
+    recipe.database.withoutDemo,
+    recipe.odoo.version,
+    recipe.database.postInit,
+]))
+    .digest("hex")
+    .slice(0, 8);
+const DAY_MS = 86_400_000;
+/**
+ * Pure prune/list decision. Docker is the truth for status; prune reasons are
+ * evaluated in strict priority order: shared shield, vanished stack, deleted
+ * root dir, deleted branch, staleness (only when `olderThanDays` is set).
+ * Rows with no probe entry are conservatively kept.
+ */
+export const classifyEnvironments = (input) => {
+    const dockerByName = new Map(input.dockerProjects.map((p) => [p.name, p.running]));
+    const nowMs = Date.parse(input.now);
+    return input.rows.map((row) => {
+        const running = dockerByName.get(row.composeProject);
+        const status = running === undefined ? "vanished" : running ? "running" : "stopped";
+        const probe = input.probes.get(row.composeProject) ?? {
+            rootDirExists: true,
+            branchExists: null,
+        };
+        const stale = input.olderThanDays !== null &&
+            nowMs - Date.parse(row.lastUsedAt) > input.olderThanDays * DAY_MS;
+        const reason = row.shared && !input.allowShared
+            ? "shared-skipped"
+            : status === "vanished"
+                ? "vanished"
+                : !probe.rootDirExists
+                    ? "gone-rootdir"
+                    : probe.branchExists === false
+                        ? "gone-branch"
+                        : stale
+                            ? "stale"
+                            : "keep";
+        return { row, status, reason };
+    });
+};
+/**
+ * Pure reset-path decision for `reset-db`/`setup`. Snapshots are only ever
+ * planned for names within `TEMPLATE_BASE_NAME_BUDGET` — over-budget names
+ * (explicit overrides) degrade every snapshot outcome to a plain `full`.
+ */
+export const decideResetPath = (input) => {
+    const snapshotFits = input.databaseName.length <= TEMPLATE_BASE_NAME_BUDGET;
+    if (input.hasOverrides)
+        return "full";
+    if (input.refreshTemplate)
+        return snapshotFits ? "full-then-snapshot" : "full";
+    if (input.noTemplate)
+        return "full";
+    if (input.row !== undefined &&
+        input.row.templateDb !== null &&
+        input.row.templateKey === input.expectedKey &&
+        snapshotFits) {
+        return "restore";
+    }
+    return snapshotFits ? "full-then-snapshot" : "full";
+};
+//# sourceMappingURL=environment.js.map

package/dist/core/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/core/environment.ts"],"names":[],"mappings":"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"}

package/dist/core/port-allocator.d.ts

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { ConfigValidationError } from "../errors/errors.js";
+export type PortHashAlgorithm = "fnv1a32" | "posix-cksum";
+/** FNV-1a 32-bit hash; stable basis for port offsets. */
+export declare const fnv1a32: (input: string) => number;
+/**
+ * POSIX 1003.2 `cksum` CRC: polynomial 0x04C11DB7 fed MSB-first with initial
+ * value 0 over the UTF-8 message bytes, then over the message length encoded
+ * least-significant byte first with leading zero bytes stripped (zero length
+ * contributes no bytes), finally ones-complemented. Bit-for-bit identical to
+ * the coreutils/BSD `cksum` binary — this is what reproduces the bash
+ * `cksum <<< "$db" | awk '{print $1}'` port derivation.
+ */
+export declare const posixCksum: (input: string) => number;
+export declare const derivePorts: (options: {
+    readonly databaseName: string;
+    readonly ports: {
+        readonly odooBase: number;
+        readonly companionBase: number;
+        readonly range: number;
+        readonly hashAlgorithm: PortHashAlgorithm;
+    };
+    readonly companionApps: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    readonly envHttpPort: string | undefined;
+}) => Effect.Effect<{
+    readonly odooHttpPort: number;
+    readonly companionPorts: ReadonlyMap<string, number>;
+}, ConfigValidationError>;

package/dist/core/port-allocator.js

@@ -0,0 +1,58 @@
+import { Effect } from "effect";
+import { ConfigValidationError } from "../errors/errors.js";
+/** FNV-1a 32-bit hash; stable basis for port offsets. */
+export const fnv1a32 = (input) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+};
+/**
+ * POSIX 1003.2 `cksum` CRC: polynomial 0x04C11DB7 fed MSB-first with initial
+ * value 0 over the UTF-8 message bytes, then over the message length encoded
+ * least-significant byte first with leading zero bytes stripped (zero length
+ * contributes no bytes), finally ones-complemented. Bit-for-bit identical to
+ * the coreutils/BSD `cksum` binary — this is what reproduces the bash
+ * `cksum <<< "$db" | awk '{print $1}'` port derivation.
+ */
+export const posixCksum = (input) => {
+    let crc = 0;
+    const feed = (byte) => {
+        crc = (crc ^ (byte << 24)) >>> 0;
+        for (let bit = 0; bit < 8; bit++) {
+            crc = ((crc & 0x80000000) !== 0 ? (crc << 1) ^ 0x04c11db7 : crc << 1) >>> 0;
+        }
+    };
+    const bytes = new TextEncoder().encode(input);
+    for (const byte of bytes)
+        feed(byte);
+    for (let length = bytes.length; length > 0; length = Math.floor(length / 256)) {
+        feed(length & 0xff);
+    }
+    return ~crc >>> 0;
+};
+const hashFor = (algorithm) => algorithm === "posix-cksum" ? posixCksum : fnv1a32;
+export const derivePorts = (options) => {
+    const offset = hashFor(options.ports.hashAlgorithm)(options.databaseName) % options.ports.range;
+    let odooHttpPort = options.ports.odooBase + offset;
+    if (options.envHttpPort !== undefined) {
+        const parsed = Number.parseInt(options.envHttpPort, 10);
+        if (!Number.isInteger(parsed) ||
+            String(parsed) !== options.envHttpPort.trim() ||
+            parsed < 1 ||
+            parsed > 65535) {
+            return Effect.fail(new ConfigValidationError({
+                issues: [`ODOO_HTTP_PORT must be an integer port, got "${options.envHttpPort}"`],
+            }));
+        }
+        odooHttpPort = parsed;
+    }
+    const companionPorts = new Map();
+    options.companionApps.forEach((app, index) => {
+        companionPorts.set(app.name, options.ports.companionBase + offset + index);
+    });
+    return Effect.succeed({ odooHttpPort, companionPorts });
+};
+//# sourceMappingURL=port-allocator.js.map

package/dist/core/port-allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-allocator.js","sourceRoot":"","sources":["../../src/core/port-allocator.ts"],"names":[],"mappings":"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"}

package/dist/core/project-recipe.d.ts

@@ -0,0 +1,163 @@
+import type { PortHashAlgorithm } from "./port-allocator.js";
+export declare const CANONICAL_ENV_VARS: readonly ["ODOO_DATABASE", "E2E_ODOO_DB", "ODOO_BASE_URL", "ODOO_HTTP_PORT", "ODOO_COMPOSE_PROJECT_NAME"];
+export type CanonicalEnvVar = (typeof CANONICAL_ENV_VARS)[number];
+export type OdooAddonMount = {
+    readonly host: string;
+    readonly container: string;
+    /** allow host paths outside the project root (default false) */
+    readonly allowOutsideRepo?: boolean;
+};
+export type PostInitHook = {
+    readonly type: "odoo-shell-file";
+    readonly file: string;
+} | {
+    readonly type: "odoo-shell-inline";
+    readonly code: string;
+} | {
+    readonly type: "set-ir-config-parameter";
+    readonly key: string;
+    readonly value: string;
+} | {
+    readonly type: "command";
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly cwd?: string;
+};
+export type CompanionAppConfig = {
+    readonly name: string;
+    readonly cwd: string;
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    /** env var name that receives the allocated port */
+    readonly portEnv?: string;
+    /** env var name that receives the app's http://localhost:<port> URL */
+    readonly urlEnv?: string;
+    /** extra env; values may reference canonical vars as "$ODOO_DATABASE" etc. */
+    readonly env?: Readonly<Record<string, string>>;
+};
+export type PackageManagerStep = {
+    readonly cwd: string;
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+};
+export type OdooProjectConfig = {
+    readonly id: string;
+    readonly dbPrefix: string;
+    readonly sharedDatabase?: string;
+    readonly sharedBranches?: ReadonlyArray<string>;
+    /** leading branch type segments stripped (at most one) before deriving the database name */
+    readonly stripBranchPrefixes?: ReadonlyArray<string>;
+};
+export type OdooRuntimeConfig = {
+    readonly version: string;
+    readonly serviceName?: string;
+    readonly databaseServiceName?: string;
+    readonly postgresImage?: string;
+    readonly configFile?: string;
+    readonly dockerfile?: string;
+    readonly imageName?: string;
+    readonly addons: ReadonlyArray<OdooAddonMount>;
+    /** path to a local Odoo source checkout, or "docker-only" */
+    readonly source?: string;
+};
+export type OdooDatabaseConfig = {
+    readonly initialModules?: ReadonlyArray<string>;
+    /** Odoo --without-demo value; false disables the flag entirely */
+    readonly withoutDemo?: string | false;
+    readonly postInit?: ReadonlyArray<PostInitHook>;
+};
+export type OdooAgenticDevConfigInput = {
+    readonly project: OdooProjectConfig;
+    readonly ports?: {
+        readonly odooBase?: number;
+        readonly companionBase?: number;
+        readonly range?: number;
+        /** offset hash over the database name; "posix-cksum" reproduces bash `cksum` tooling */
+        readonly hashAlgorithm?: PortHashAlgorithm;
+    };
+    readonly odoo: OdooRuntimeConfig;
+    readonly database?: OdooDatabaseConfig;
+    readonly setup?: {
+        readonly submodules?: boolean;
+        readonly packageManagers?: ReadonlyArray<PackageManagerStep>;
+    };
+    readonly compose?: {
+        /** escape hatch: project-supplied compose file instead of the generated one */
+        readonly file?: string;
+    };
+    readonly worktree?: {
+        /** project-root files copied into a fresh worktree when they exist (e.g. ".env.e2e") */
+        readonly copyFiles?: ReadonlyArray<string>;
+        /** prefix for the branch `worktree create` makes (default "worktree-") */
+        readonly branchPrefix?: string;
+    };
+    readonly test?: {
+        /** profile name → extra odoo CLI args, e.g. { payment: ["--test-tags", "payment"] } */
+        readonly profiles?: Readonly<Record<string, ReadonlyArray<string>>>;
+    };
+    /** compatibility aliases: alias env var name → any assembled env key (canonical or companion portEnv/urlEnv) */
+    readonly envAliases?: Readonly<Record<string, string>>;
+    readonly companionApps?: ReadonlyArray<CompanionAppConfig>;
+    /** stale-environment cleanup: warn by default, prune automatically when auto */
+    readonly cleanup?: {
+        readonly maxAgeDays?: number;
+        readonly auto?: boolean;
+    };
+};
+/** Normalized config: every default applied, optionals resolved. */
+export type OdooAgenticDevConfig = {
+    readonly project: {
+        readonly id: string;
+        readonly dbPrefix: string;
+        readonly sharedDatabase: string | null;
+        readonly sharedBranches: ReadonlyArray<string>;
+        readonly stripBranchPrefixes: ReadonlyArray<string>;
+    };
+    readonly ports: {
+        readonly odooBase: number;
+        readonly companionBase: number;
+        readonly range: number;
+        readonly hashAlgorithm: PortHashAlgorithm;
+    };
+    readonly odoo: {
+        readonly version: string;
+        readonly serviceName: string;
+        readonly databaseServiceName: string;
+        readonly postgresImage: string;
+        readonly configFile: string | null;
+        readonly dockerfile: string | null;
+        readonly imageName: string | null;
+        readonly addons: ReadonlyArray<OdooAddonMount>;
+        readonly source: string | null;
+    };
+    readonly database: {
+        readonly initialModules: ReadonlyArray<string>;
+        readonly withoutDemo: string | false;
+        readonly postInit: ReadonlyArray<PostInitHook>;
+    };
+    readonly setup: {
+        readonly submodules: boolean;
+        readonly packageManagers: ReadonlyArray<PackageManagerStep>;
+    };
+    readonly compose: {
+        readonly file: string | null;
+    };
+    readonly worktree: {
+        readonly copyFiles: ReadonlyArray<string>;
+        readonly branchPrefix: string;
+    };
+    readonly test: {
+        readonly profiles: Readonly<Record<string, ReadonlyArray<string>>>;
+    };
+    readonly envAliases: Readonly<Record<string, string>>;
+    readonly companionApps: ReadonlyArray<CompanionAppConfig>;
+    readonly cleanup: {
+        readonly maxAgeDays: number;
+        readonly auto: boolean;
+    };
+};
+/**
+ * Identity helper preserving literal types. Runtime validation happens when the
+ * CLI loads the file (config/schema.ts), so plain JS configs are covered too.
+ */
+export declare const defineConfig: (config: OdooAgenticDevConfigInput) => OdooAgenticDevConfigInput;

package/dist/core/project-recipe.js

@@ -0,0 +1,13 @@
+export const CANONICAL_ENV_VARS = [
+    "ODOO_DATABASE",
+    "E2E_ODOO_DB",
+    "ODOO_BASE_URL",
+    "ODOO_HTTP_PORT",
+    "ODOO_COMPOSE_PROJECT_NAME",
+];
+/**
+ * Identity helper preserving literal types. Runtime validation happens when the
+ * CLI loads the file (config/schema.ts), so plain JS configs are covered too.
+ */
+export const defineConfig = (config) => config;
+//# sourceMappingURL=project-recipe.js.map

package/dist/core/project-recipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-recipe.js","sourceRoot":"","sources":["../../src/core/project-recipe.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,eAAe;IACf,aAAa;IACb,eAAe;IACf,gBAAgB;IAChB,2BAA2B;CACnB,CAAC;AA0JX;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAiC,EAA6B,EAAE,CAC3F,MAAM,CAAC"}

package/dist/core/safety.d.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect";
+import { ConfigValidationError, SharedDatabaseProtectionError } from "../errors/errors.js";
+export declare const isSharedDatabase: (databaseName: string, sharedDatabase: string | null) => boolean;
+export declare const assertSharedDatabaseAllowed: (options: {
+    readonly databaseName: string;
+    readonly sharedDatabase: string | null;
+    readonly allowShared: boolean;
+    /** command name for the error message, e.g. "reset-db" */
+    readonly action: string;
+}) => Effect.Effect<void, SharedDatabaseProtectionError>;
+export declare const assertComposeProjectName: (name: string) => Effect.Effect<string, ConfigValidationError>;

package/dist/core/safety.js

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { ConfigValidationError, SharedDatabaseProtectionError } from "../errors/errors.js";
+const COMPOSE_PROJECT_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
+export const isSharedDatabase = (databaseName, sharedDatabase) => sharedDatabase !== null && databaseName === sharedDatabase;
+export const assertSharedDatabaseAllowed = (options) => isSharedDatabase(options.databaseName, options.sharedDatabase) && !options.allowShared
+    ? Effect.fail(new SharedDatabaseProtectionError({
+        database: options.databaseName,
+        action: options.action,
+    }))
+    : Effect.void;
+export const assertComposeProjectName = (name) => COMPOSE_PROJECT_PATTERN.test(name)
+    ? Effect.succeed(name)
+    : Effect.fail(new ConfigValidationError({
+        issues: [`compose project name "${name}" is empty or unsafe`],
+    }));
+//# sourceMappingURL=safety.js.map

package/dist/core/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../src/core/safety.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAE3F,MAAM,uBAAuB,GAAG,uBAAuB,CAAC;AAExD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,YAAoB,EAAE,cAA6B,EAAW,EAAE,CAC/F,cAAc,KAAK,IAAI,IAAI,YAAY,KAAK,cAAc,CAAC;AAE7D,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,OAM3C,EAAsD,EAAE,CACvD,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW;IACpF,CAAC,CAAC,MAAM,CAAC,IAAI,CACT,IAAI,6BAA6B,CAAC;QAChC,QAAQ,EAAE,OAAO,CAAC,YAAY;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CACH;IACH,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;AAElB,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,IAAY,EACkC,EAAE,CAChD,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC;IAChC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;IACtB,CAAC,CAAC,MAAM,CAAC,IAAI,CACT,IAAI,qBAAqB,CAAC;QACxB,MAAM,EAAE,CAAC,yBAAyB,IAAI,sBAAsB,CAAC;KAC9D,CAAC,CACH,CAAC"}

package/dist/core/worktree-context.d.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { ConfigValidationError } from "../errors/errors.js";
+import type { UnsafeDatabaseNameError } from "../errors/errors.js";
+import type { OdooAgenticDevConfig } from "./project-recipe.js";
+export type GitState = {
+    readonly _tag: "Branch";
+    readonly branch: string;
+} | {
+    readonly _tag: "Detached";
+} | {
+    readonly _tag: "NotARepo";
+};
+export type WorktreeContext = {
+    readonly rootDir: string;
+    readonly worktreeName: string;
+    /** the real git branch; null when detached / not a repo (name overrides don't count) */
+    readonly branch: string | null;
+    readonly databaseName: string;
+    readonly composeProjectName: string;
+    readonly odooHttpPort: number;
+    readonly odooBaseUrl: string;
+    readonly companionPorts: ReadonlyMap<string, number>;
+    readonly env: Record<string, string>;
+};
+export declare const buildWorktreeContext: (options: {
+    readonly rootDir: string;
+    readonly recipe: OdooAgenticDevConfig;
+    readonly env: Record<string, string | undefined>;
+    readonly git: GitState;
+}) => Effect.Effect<WorktreeContext, ConfigValidationError | UnsafeDatabaseNameError>;
+/** Replace $NAME tokens with values from `env`; unknown tokens are left intact. */
+export declare const substituteEnvTokens: (value: string, env: Record<string, string>) => string;