@owlmeans/viable-sdk 0.1.18-rc.1

package/build/index.d.ts

@@ -0,0 +1,13 @@
+export * from './consts.js';
+export * from './errors.js';
+export * from './project/marker.js';
+export * from './project/env.js';
+export * from './project/setup.js';
+export * from './context/index.js';
+export * from './api/index.js';
+export * from './session/index.js';
+export * from './task/index.js';
+export * from './harness/index.js';
+export * from './tools/index.js';
+export type * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA;AAChC,mBAAmB,YAAY,CAAA"}

package/build/index.js

@@ -0,0 +1,12 @@
+export * from './consts.js';
+export * from './errors.js';
+export * from './project/marker.js';
+export * from './project/env.js';
+export * from './project/setup.js';
+export * from './context/index.js';
+export * from './api/index.js';
+export * from './session/index.js';
+export * from './task/index.js';
+export * from './harness/index.js';
+export * from './tools/index.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,qBAAqB,CAAA;AACnC,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA"}

package/build/project/env.d.ts

@@ -0,0 +1,108 @@
+import type { ConfigurePayload, ConfigureResult, ConnectServices } from '@owlmeans/viable-common';
+/**
+ * The target's `.env` files — the one thing about a local project the platform does not own.
+ *
+ * A slot's configuration is pushed into a pod and the pod's environment is the platform's to
+ * compose. On a developer's machine the same values live in a file the developer also writes: the
+ * database URL is theirs (nothing provisions a database on a laptop), and so is anything else
+ * they added. So a configure push rewrites only what it wrote last time — the block between the
+ * two markers — and every line outside it survives untouched.
+ */
+/**
+ * Keys the target cannot authenticate without.
+ *
+ * Reported exactly like the publisher's `ConfigureAck.missing`: a key with an EMPTY value counts
+ * as MISSING, because a push that ran before a secret existed leaves one behind, and a target
+ * holding `OIDC_CLIENT=''` is a target whose users can never sign in — with nothing anywhere
+ * saying so.
+ */
+export declare const REQUIRED_ENV_KEYS: string[];
+export interface TargetEnv {
+    /** Project-relative path → the values that file declares. */
+    files: Record<string, Record<string, string>>;
+    /** Everything the target's processes see, later files overriding earlier ones. */
+    values: Record<string, string>;
+}
+/**
+ * Parse a `.env` body.
+ *
+ * Deliberately small: `KEY=value`, an optional `export ` prefix, `#` comments, and one level of
+ * quoting. A dotenv library would add a dependency for a format the platform itself writes, and
+ * anything it understands that this does not is something the target's own runtime would have to
+ * understand too.
+ */
+export declare const parseEnv: (content: string) => Record<string, string>;
+/**
+ * The api's and the worker's environment — the process side of the target.
+ *
+ * Everything a server may hold lives here and nowhere else: the database URL, the queue URL, the
+ * OIDC secret.
+ */
+export declare const ROOT_ENV_FILE = ".env";
+/**
+ * The browser bundle's environment.
+ *
+ * A SEPARATE file, and the separation is the whole leak boundary: whatever is in it gets compiled
+ * into a bundle anybody can read, so nothing may reach it by merging in the server's file.
+ */
+export declare const webEnvFile: (dir: string) => string;
+/** The env files a target has, in the order a later one overrides an earlier one. */
+export declare const envFilePaths: (dir: string) => string[];
+/** One env file's values; `{}` for a file that is not there. */
+export declare const readEnvFile: (dir: string, file: string) => Promise<Record<string, string>>;
+/** Every env file the target has, parsed. */
+export declare const readEnv: (dir: string) => Promise<TargetEnv>;
+/**
+ * Write the platform's block into each named file, keeping every line the user wrote.
+ *
+ * The block is delimited rather than diffed because the two writers have no other way to agree on
+ * ownership: the platform composes its half whole (it is the only side that knows the OIDC client
+ * and its secret) and the user's half is arbitrary. A file with no block yet gets one appended; a
+ * file that does not exist is created with the block as its whole content.
+ */
+export declare const writeEnv: (dir: string, payload: ConfigurePayload) => Promise<ConfigureResult>;
+/**
+ * The same verdict a configure push answers with, without writing anything.
+ *
+ * A connector needs it before it asks the platform for work — a run that needs a database and a
+ * target that has none is a job that will block, and saying so up front is cheaper than finding
+ * out from a boot check.
+ */
+export declare const envStatus: (dir: string, probe?: Array<keyof ConnectServices>) => Promise<ConfigureResult>;
+/** The file with the platform's block cut out — everything the user wrote, and only that. */
+export declare const outsideManagedBlock: (existing: string) => string;
+/**
+ * Stand down from every key the user has assigned themselves.
+ *
+ * "Everything outside the block is yours" has to be true of the VALUES, not only of the lines. A
+ * `.env` gives the last assignment of a key, and the block is appended, so a platform line silently
+ * outranked whatever the user wrote above it — `DATABASE_URL` included, which is the one value the
+ * platform cannot supply and the setup guide tells people to write themselves. The result was an
+ * application connecting to the placeholder no matter what its owner put in the file.
+ *
+ * A yielded key is replaced by a comment rather than dropped, so the file says why the platform is
+ * not setting something it normally would.
+ */
+export declare const yieldToUser: (existing: string, content: string) => string;
+/**
+ * Replace what sits between the markers, and nothing else.
+ *
+ * A BEGIN with no END — a file truncated mid-write, or hand-edited — is rewritten to the end of
+ * the file rather than left alone: the alternative is a block that grows a second copy of itself
+ * on every push, and the text after a lost END was the platform's anyway.
+ */
+export declare const replaceManagedBlock: (existing: string, content: string) => string;
+/**
+ * The host and port a connection URL names.
+ *
+ * `null` for anything unparseable, so a malformed value degrades to "not reachable" rather than
+ * throwing somewhere a caller has no branch for it.
+ */
+export declare const serviceEndpoint: (url: string | undefined) => {
+    host: string;
+    port: number;
+} | null;
+/** Whether something is listening where a connection string points. Exported for the setup flow. */
+export declare const probeUrl: (url: string | undefined) => Promise<boolean>;
+export declare const probePort: (host: string, port: number, timeoutMs?: number) => Promise<boolean>;
+//# sourceMappingURL=env.d.ts.map

package/build/project/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/project/env.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAKjG;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,UAAoD,CAAA;AAOlF,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC7C,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,YAAa,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAkB/D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAS,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,QAAS,MAAM,KAAG,MACyC,CAAA;AAElF,qFAAqF;AACrF,eAAO,MAAM,YAAY,QAAS,MAAM,KAAG,MAAM,EAAsC,CAAA;AAEvF,gEAAgE;AAChE,eAAO,MAAM,WAAW,QAAe,MAAM,QAAQ,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI3F,CAAA;AAED,6CAA6C;AAC7C,eAAO,MAAM,OAAO,QAAe,MAAM,KAAG,OAAO,CAAC,SAAS,CAU5D,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,QAAe,MAAM,WAAW,gBAAgB,KAAG,OAAO,CAAC,eAAe,CAqB9F,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,QACf,MAAM,UAAS,KAAK,CAAC,MAAM,eAAe,CAAC,KAC/C,OAAO,CAAC,eAAe,CAQzB,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,aAAc,MAAM,KAAG,MAStD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,aAAc,MAAM,WAAW,MAAM,KAAG,MAU/D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,aAAc,MAAM,WAAW,MAAM,KAAG,MAevE,CAAA;AAoBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAS,MAAM,GAAG,SAAS,KAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAc1F,CAAA;AAED,oGAAoG;AACpG,eAAO,MAAM,QAAQ,QAAe,MAAM,GAAG,SAAS,KAAG,OAAO,CAAC,OAAO,CAIvE,CAAA;AAED,eAAO,MAAM,SAAS,SACd,MAAM,QAAQ,MAAM,yBACzB,OAAO,CAAC,OAAO,CAWhB,CAAA"}

package/build/project/env.js

@@ -0,0 +1,233 @@
+import fs from 'fs-extra';
+import net from 'node:net';
+import p from 'node:path';
+import { CONNECT_ENV_BEGIN, CONNECT_ENV_END, SubProject } from '@owlmeans/viable-common';
+import { confineToProject } from '../executor/files.js';
+import { subprojectDir, targetPaths } from '../executor/layout.js';
+/**
+ * The target's `.env` files — the one thing about a local project the platform does not own.
+ *
+ * A slot's configuration is pushed into a pod and the pod's environment is the platform's to
+ * compose. On a developer's machine the same values live in a file the developer also writes: the
+ * database URL is theirs (nothing provisions a database on a laptop), and so is anything else
+ * they added. So a configure push rewrites only what it wrote last time — the block between the
+ * two markers — and every line outside it survives untouched.
+ */
+/**
+ * Keys the target cannot authenticate without.
+ *
+ * Reported exactly like the publisher's `ConfigureAck.missing`: a key with an EMPTY value counts
+ * as MISSING, because a push that ran before a secret existed leaves one behind, and a target
+ * holding `OIDC_CLIENT=''` is a target whose users can never sign in — with nothing anywhere
+ * saying so.
+ */
+export const REQUIRED_ENV_KEYS = ['OIDC_ISSUER_URL', 'OIDC_CLIENT', 'OIDC_SECRET'];
+/** How long a service probe waits before calling a port unreachable. */
+const PROBE_TIMEOUT_MS = 1_500;
+const DEFAULT_PORTS = { postgres: 5432, postgresql: 5432, redis: 6379, rediss: 6379, valkey: 6379 };
+/**
+ * Parse a `.env` body.
+ *
+ * Deliberately small: `KEY=value`, an optional `export ` prefix, `#` comments, and one level of
+ * quoting. A dotenv library would add a dependency for a format the platform itself writes, and
+ * anything it understands that this does not is something the target's own runtime would have to
+ * understand too.
+ */
+export const parseEnv = (content) => {
+    const values = {};
+    for (const raw of content.split('\n')) {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (match == null)
+            continue;
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"') && value.length > 1)
+            || (value.startsWith("'") && value.endsWith("'") && value.length > 1)) {
+            value = value.slice(1, -1);
+        }
+        values[match[1]] = value;
+    }
+    return values;
+};
+/**
+ * The api's and the worker's environment — the process side of the target.
+ *
+ * Everything a server may hold lives here and nowhere else: the database URL, the queue URL, the
+ * OIDC secret.
+ */
+export const ROOT_ENV_FILE = '.env';
+/**
+ * The browser bundle's environment.
+ *
+ * A SEPARATE file, and the separation is the whole leak boundary: whatever is in it gets compiled
+ * into a bundle anybody can read, so nothing may reach it by merging in the server's file.
+ */
+export const webEnvFile = (dir) => `${targetPaths(dir).dir}/${subprojectDir(dir, SubProject.Web)}/${ROOT_ENV_FILE}`;
+/** The env files a target has, in the order a later one overrides an earlier one. */
+export const envFilePaths = (dir) => [ROOT_ENV_FILE, webEnvFile(dir)];
+/** One env file's values; `{}` for a file that is not there. */
+export const readEnvFile = async (dir, file) => {
+    const content = await fs.readFile(confineToProject(dir, file), 'utf-8').catch(() => null);
+    return content == null ? {} : parseEnv(content);
+};
+/** Every env file the target has, parsed. */
+export const readEnv = async (dir) => {
+    const files = {};
+    let values = {};
+    for (const file of envFilePaths(dir)) {
+        const parsed = await readEnvFile(dir, file);
+        files[file] = parsed;
+        values = { ...values, ...parsed };
+    }
+    return { files, values };
+};
+/**
+ * Write the platform's block into each named file, keeping every line the user wrote.
+ *
+ * The block is delimited rather than diffed because the two writers have no other way to agree on
+ * ownership: the platform composes its half whole (it is the only side that knows the OIDC client
+ * and its secret) and the user's half is arbitrary. A file with no block yet gets one appended; a
+ * file that does not exist is created with the block as its whole content.
+ */
+export const writeEnv = async (dir, payload) => {
+    const written = [];
+    for (const file of payload.files ?? []) {
+        const path = confineToProject(dir, file.path);
+        const existing = await fs.readFile(path, 'utf-8').catch(() => '');
+        const next = replaceManagedBlock(existing, yieldToUser(existing, file.content ?? ''));
+        if (next !== existing) {
+            await fs.ensureDir(p.dirname(path));
+            await fs.writeFile(path, next);
+        }
+        written.push(file.path);
+    }
+    const { values } = await readEnv(dir);
+    return {
+        written,
+        missing: REQUIRED_ENV_KEYS.filter(key => (values[key] ?? '') === ''),
+        services: await probeServices(values, payload.probe),
+    };
+};
+/**
+ * The same verdict a configure push answers with, without writing anything.
+ *
+ * A connector needs it before it asks the platform for work — a run that needs a database and a
+ * target that has none is a job that will block, and saying so up front is cheaper than finding
+ * out from a boot check.
+ */
+export const envStatus = async (dir, probe = ['db', 'valkey']) => {
+    const { values } = await readEnv(dir);
+    return {
+        written: [],
+        missing: REQUIRED_ENV_KEYS.filter(key => (values[key] ?? '') === ''),
+        services: await probeServices(values, probe),
+    };
+};
+/** The file with the platform's block cut out — everything the user wrote, and only that. */
+export const outsideManagedBlock = (existing) => {
+    const begin = existing.indexOf(CONNECT_ENV_BEGIN);
+    if (begin < 0)
+        return existing;
+    const end = existing.indexOf(CONNECT_ENV_END, begin);
+    return end < 0
+        ? existing.slice(0, begin)
+        : `${existing.slice(0, begin)}${existing.slice(end + CONNECT_ENV_END.length)}`;
+};
+/**
+ * Stand down from every key the user has assigned themselves.
+ *
+ * "Everything outside the block is yours" has to be true of the VALUES, not only of the lines. A
+ * `.env` gives the last assignment of a key, and the block is appended, so a platform line silently
+ * outranked whatever the user wrote above it — `DATABASE_URL` included, which is the one value the
+ * platform cannot supply and the setup guide tells people to write themselves. The result was an
+ * application connecting to the placeholder no matter what its owner put in the file.
+ *
+ * A yielded key is replaced by a comment rather than dropped, so the file says why the platform is
+ * not setting something it normally would.
+ */
+export const yieldToUser = (existing, content) => {
+    const theirs = parseEnv(outsideManagedBlock(existing));
+    if (Object.keys(theirs).length < 1)
+        return content;
+    return content.split('\n').map(raw => {
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(raw.trim());
+        if (match == null || !(match[1] in theirs))
+            return raw;
+        return `# ${match[1]} is set in your own lines, so this block leaves it to you.`;
+    }).join('\n');
+};
+/**
+ * Replace what sits between the markers, and nothing else.
+ *
+ * A BEGIN with no END — a file truncated mid-write, or hand-edited — is rewritten to the end of
+ * the file rather than left alone: the alternative is a block that grows a second copy of itself
+ * on every push, and the text after a lost END was the platform's anyway.
+ */
+export const replaceManagedBlock = (existing, content) => {
+    const body = content.replace(/^\n+|\n+$/g, '');
+    const block = `${CONNECT_ENV_BEGIN}\n${body === '' ? '' : `${body}\n`}${CONNECT_ENV_END}\n`;
+    const begin = existing.indexOf(CONNECT_ENV_BEGIN);
+    if (begin < 0) {
+        const prefix = existing === '' || existing.endsWith('\n') ? existing : `${existing}\n`;
+        return `${prefix}${block}`;
+    }
+    const end = existing.indexOf(CONNECT_ENV_END, begin);
+    const after = end < 0 ? existing.length : end + CONNECT_ENV_END.length;
+    return `${existing.slice(0, begin)}${block}${existing.slice(after).replace(/^\n/, '')}`;
+};
+/**
+ * What this machine actually provides.
+ *
+ * Reported, never assumed — the platform provisions nothing here, so the only honest answer comes
+ * from a connect attempt. A service the caller did not ask about stays `false` rather than
+ * becoming an unrequested round trip.
+ */
+const probeServices = async (values, probe) => {
+    const wanted = new Set(probe ?? []);
+    return {
+        db: wanted.has('db') ? await probeUrl(values.DATABASE_URL) : false,
+        valkey: wanted.has('valkey') ? await probeUrl(values.VALKEY_URL) : false,
+    };
+};
+/**
+ * The host and port a connection URL names.
+ *
+ * `null` for anything unparseable, so a malformed value degrades to "not reachable" rather than
+ * throwing somewhere a caller has no branch for it.
+ */
+export const serviceEndpoint = (url) => {
+    if (url == null || url === '')
+        return null;
+    try {
+        const parsed = new URL(url);
+        const port = parsed.port !== ''
+            ? parseInt(parsed.port)
+            : DEFAULT_PORTS[parsed.protocol.replace(':', '')];
+        if (parsed.hostname === '' || port == null || Number.isNaN(port))
+            return null;
+        return { host: parsed.hostname, port };
+    }
+    catch {
+        return null;
+    }
+};
+/** Whether something is listening where a connection string points. Exported for the setup flow. */
+export const probeUrl = async (url) => {
+    const endpoint = serviceEndpoint(url);
+    return endpoint == null ? false : await probePort(endpoint.host, endpoint.port);
+};
+export const probePort = async (host, port, timeoutMs = PROBE_TIMEOUT_MS) => await new Promise(resolve => {
+    const socket = net.connect({ host, port });
+    const done = (value) => {
+        socket.removeAllListeners();
+        socket.destroy();
+        resolve(value);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+});
+//# sourceMappingURL=env.js.map

package/build/project/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/project/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,UAAU,CAAA;AACzB,OAAO,GAAG,MAAM,UAAU,CAAA;AAC1B,OAAO,CAAC,MAAM,WAAW,CAAA;AAEzB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AAGxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAElE;;;;;;;;GAQG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,iBAAiB,EAAE,aAAa,EAAE,aAAa,CAAC,CAAA;AAElF,wEAAwE;AACxE,MAAM,gBAAgB,GAAG,KAAK,CAAA;AAE9B,MAAM,aAAa,GAA2B,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAA;AAS3H;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,OAAe,EAA0B,EAAE;IAClE,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;QACvB,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAEjD,MAAM,KAAK,GAAG,qDAAqD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC9E,IAAI,KAAK,IAAI,IAAI;YAAE,SAAQ;QAE3B,IAAI,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;eACjE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;YACxE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAA;IAC1B,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAW,EAAU,EAAE,CAChD,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,IAAI,aAAa,EAAE,CAAA;AAElF,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAW,EAAY,EAAE,CAAC,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AAEvF,gEAAgE;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,GAAW,EAAE,IAAY,EAAmC,EAAE;IAC9F,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;IAEzF,OAAO,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AACjD,CAAC,CAAA;AAED,6CAA6C;AAC7C,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAAE,GAAW,EAAsB,EAAE;IAC/D,MAAM,KAAK,GAA2C,EAAE,CAAA;IACxD,IAAI,MAAM,GAA2B,EAAE,CAAA;IACvC,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAA;QACpB,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;IACnC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC1B,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAW,EAAE,OAAyB,EAA4B,EAAE;IACjG,MAAM,OAAO,GAAa,EAAE,CAAA;IAE5B,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;QAC7C,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;QACjE,MAAM,IAAI,GAAG,mBAAmB,CAAC,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAA;QACrF,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;YACnC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAChC,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;IAErC,OAAO;QACL,OAAO;QACP,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;QACpE,QAAQ,EAAE,MAAM,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC;KACrD,CAAA;AACH,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,GAAW,EAAE,KAAK,GAAiC,CAAC,IAAI,EAAE,QAAQ,CAAC,EACzC,EAAE;IAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;IAErC,OAAO;QACL,OAAO,EAAE,EAAE;QACX,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;QACpE,QAAQ,EAAE,MAAM,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC;KAC7C,CAAA;AACH,CAAC,CAAA;AAED,6FAA6F;AAC7F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAgB,EAAU,EAAE;IAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACjD,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAA;IAE9B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,CAAA;IAEpD,OAAO,GAAG,GAAG,CAAC;QACZ,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;QAC1B,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,EAAE,CAAA;AAClF,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAgB,EAAE,OAAe,EAAU,EAAE;IACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAA;IACtD,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAA;IAElD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;QACnC,MAAM,KAAK,GAAG,6CAA6C,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;QAC5E,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;YAAE,OAAO,GAAG,CAAA;QAEtD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,4DAA4D,CAAA;IAClF,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,QAAgB,EAAE,OAAe,EAAU,EAAE;IAC/E,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;IAC9C,MAAM,KAAK,GAAG,GAAG,iBAAiB,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,GAAG,eAAe,IAAI,CAAA;IAE3F,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAA;IACjD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,QAAQ,KAAK,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,CAAA;QAEtF,OAAO,GAAG,MAAM,GAAG,KAAK,EAAE,CAAA;IAC5B,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,CAAA;IACpD,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,eAAe,CAAC,MAAM,CAAA;IAEtE,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAA;AACzF,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,aAAa,GAAG,KAAK,EACzB,MAA8B,EAAE,KAAoC,EAC1C,EAAE;IAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAA;IAEnC,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK;QAClE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK;KACzE,CAAA;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAuB,EAAyC,EAAE;IAChG,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAE1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,KAAK,EAAE;YAC7B,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC;YACvB,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAA;QACnD,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE,IAAI,IAAI,IAAI,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;QAE7E,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAA;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,oGAAoG;AACpG,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAuB,EAAoB,EAAE;IAC1E,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;IAErC,OAAO,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;AACjF,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,IAAY,EAAE,IAAY,EAAE,SAAS,GAAG,gBAAgB,EACtC,EAAE,CAAC,MAAM,IAAI,OAAO,CAAU,OAAO,CAAC,EAAE;IAC1D,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,EAAE;QAC9B,MAAM,CAAC,kBAAkB,EAAE,CAAA;QAC3B,MAAM,CAAC,OAAO,EAAE,CAAA;QAChB,OAAO,CAAC,KAAK,CAAC,CAAA;IAChB,CAAC,CAAA;IACD,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAA;IAC5B,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACxC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACzC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;AACzC,CAAC,CAAC,CAAA"}

package/build/project/marker.d.ts

@@ -0,0 +1,34 @@
+import type { ConnectMarker } from '@owlmeans/viable-common';
+/**
+ * What a local project keeps so a later session knows which platform project it is.
+ *
+ * No secrets: an id, a slug and the API it belongs to. A connector attaching to a directory has
+ * nothing else to go on — the tree itself is a generated application like any other, and asking
+ * the platform "which of my projects is this" needs an id the tree already carries.
+ */
+export interface DiscoveredProject {
+    /** The directory holding `.viable/connect.json` — the project root, not where the search began. */
+    dir: string;
+    marker: ConnectMarker;
+}
+/** The marker this directory carries, or `null` when it carries none or an unreadable one. */
+export declare const readMarker: (dir: string) => Promise<ConnectMarker | null>;
+export declare const writeMarker: (dir: string, marker: ConnectMarker) => Promise<void>;
+/**
+ * Find the project a directory belongs to, by walking up.
+ *
+ * An agent is started wherever its user happened to be — usually several levels inside the tree —
+ * and every tool that acts on "this project" has to mean the same one whichever of those
+ * directories it was asked from. The walk stops at the filesystem root; a machine with no marker
+ * anywhere above answers `null`, which is how a connector knows to offer attaching rather than
+ * assuming.
+ */
+export declare const discoverProject: (startDir: string) => Promise<DiscoveredProject | null>;
+/**
+ * Whether this directory holds the generated application.
+ *
+ * Asked before a connector offers to drive a directory, so a person who pointed it at the wrong
+ * folder learns that from a sentence rather than from a build that refuses everything.
+ */
+export declare const isViableTree: (dir: string) => Promise<boolean>;
+//# sourceMappingURL=marker.d.ts.map

package/build/project/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/project/marker.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAI5D;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,mGAAmG;IACnG,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,aAAa,CAAA;CACtB;AAED,8FAA8F;AAC9F,eAAO,MAAM,UAAU,QAAe,MAAM,KAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAa1E,CAAA;AAED,eAAO,MAAM,WAAW,QAAe,MAAM,UAAU,aAAa,KAAG,OAAO,CAAC,IAAI,CAKlF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,aAAoB,MAAM,KAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAcxF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAAe,MAAM,KAAG,OAAO,CAAC,OAAO,CAClC,CAAA"}

package/build/project/marker.js

@@ -0,0 +1,54 @@
+import fs from 'fs-extra';
+import p from 'node:path';
+import { CONNECT_MARKER_DIR, CONNECT_MARKER_FILE } from '@owlmeans/viable-common';
+import { verifyTarget } from '../executor/integrity.js';
+/** The marker this directory carries, or `null` when it carries none or an unreadable one. */
+export const readMarker = async (dir) => {
+    const content = await fs.readFile(p.join(dir, CONNECT_MARKER_FILE), 'utf-8').catch(() => null);
+    if (content == null)
+        return null;
+    try {
+        const parsed = JSON.parse(content);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        // A half-written or hand-edited marker is the same as none: the connector re-attaches by
+        // slug and writes a fresh one, which is strictly better than refusing to open the project.
+        return null;
+    }
+};
+export const writeMarker = async (dir, marker) => {
+    await fs.ensureDir(p.join(dir, CONNECT_MARKER_DIR));
+    await fs.writeFile(p.join(dir, CONNECT_MARKER_FILE), `${JSON.stringify(marker, null, 2)}\n`);
+};
+/**
+ * Find the project a directory belongs to, by walking up.
+ *
+ * An agent is started wherever its user happened to be — usually several levels inside the tree —
+ * and every tool that acts on "this project" has to mean the same one whichever of those
+ * directories it was asked from. The walk stops at the filesystem root; a machine with no marker
+ * anywhere above answers `null`, which is how a connector knows to offer attaching rather than
+ * assuming.
+ */
+export const discoverProject = async (startDir) => {
+    let dir = p.resolve(startDir);
+    for (;;) {
+        const marker = await readMarker(dir);
+        if (marker != null) {
+            return { dir, marker };
+        }
+        const parent = p.dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+};
+/**
+ * Whether this directory holds the generated application.
+ *
+ * Asked before a connector offers to drive a directory, so a person who pointed it at the wrong
+ * folder learns that from a sentence rather than from a build that refuses everything.
+ */
+export const isViableTree = async (dir) => (await verifyTarget(dir)).ok;
+//# sourceMappingURL=marker.js.map

package/build/project/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.js","sourceRoot":"","sources":["../../src/project/marker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,UAAU,CAAA;AACzB,OAAO,CAAC,MAAM,WAAW,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAGjF,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAgBvD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAAE,GAAW,EAAiC,EAAE;IAC7E,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;IAC9F,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAEhC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAE3C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAuB,CAAC,CAAC,CAAC,IAAI,CAAA;IACvF,CAAC;IAAC,MAAM,CAAC;QACP,yFAAyF;QACzF,2FAA2F;QAC3F,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,GAAW,EAAE,MAAqB,EAAiB,EAAE;IACrF,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAA;IACnD,MAAM,EAAE,CAAC,SAAS,CAChB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACzE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,QAAgB,EAAqC,EAAE;IAC3F,IAAI,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC7B,SAAS,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,CAAA;QACpC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAA;QACxB,CAAC;QAED,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;YACnB,OAAO,IAAI,CAAA;QACb,CAAC;QACD,GAAG,GAAG,MAAM,CAAA;IACd,CAAC;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,GAAW,EAAoB,EAAE,CAClE,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA"}

package/build/project/setup.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What a project needs before it can run here, and what this machine already provides.
+ *
+ * The platform provisions nothing on somebody's own computer: a database and, for a project with a
+ * background worker, a queue store are the two things it cannot supply and cannot guess. So the
+ * connector's job is to find out what is already there, and where nothing is, to ASK — never to
+ * install something on a person's machine on its own initiative, and never to invent a connection
+ * string and let the failure surface later as a boot error nobody can place.
+ */
+export interface ServiceState {
+    /** A connection string is present in the project's own half of the `.env`. */
+    configured: boolean;
+    /** Something answers where it points. False for an unset URL and for one nothing listens on. */
+    reachable: boolean;
+    /** The value, with everything between the scheme and the host removed. */
+    redacted?: string;
+}
+export interface SetupReport {
+    dir: string;
+    /** Only a project with a worker needs a queue store; for the rest it is noise. */
+    needsWorker: boolean;
+    database: ServiceState;
+    queue: ServiceState;
+    /** The command-line tools the paths below depend on. */
+    tools: {
+        bun: boolean;
+        git: boolean;
+        docker: boolean;
+    };
+    platform: NodeJS.Platform;
+    /** Whether the file holding these values is kept out of the project's history. */
+    envIgnored: boolean;
+}
+/** Everything a connection string says except who is connecting. */
+export declare const redactUrl: (url: string) => string;
+/** Whether a command can be run here. `--version` rather than `which`, which Windows lacks. */
+export declare const probeCommand: (command: string) => Promise<boolean>;
+export declare const readSetupReport: (dir: string) => Promise<SetupReport>;
+/** What is still missing before the application can start. */
+export declare const missingServices: (report: SetupReport) => Array<'database' | 'queue'>;
+/**
+ * The answer a parent agent reads when the project cannot run yet.
+ *
+ * It is written as a QUESTION with three answers, because which one is right is the user's to
+ * decide and nobody else's: they may already run Postgres, they may want one installed here, or
+ * they may prefer a hosted free tier and never install anything. Guessing means either a container
+ * on somebody's machine they did not ask for, or a connection string invented for a database that
+ * does not exist — and the second surfaces minutes later as a boot error nobody can place.
+ */
+export declare const renderSetupGuide: (report: SetupReport) => string;
+/**
+ * Write the user's own service lines into their half of the `.env`.
+ *
+ * Replaces the key where it already exists outside the managed block and appends it otherwise, so
+ * running this twice leaves one line rather than two — a `.env` takes the LAST assignment, and two
+ * copies of a credential is one of them being quietly ignored.
+ */
+export declare const setUserEnv: (dir: string, values: Record<string, string>) => Promise<{
+    written: string[];
+    file: string;
+}>;
+//# sourceMappingURL=setup.d.ts.map

package/build/project/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/project/setup.ts"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAA;IACnB,gGAAgG;IAChG,SAAS,EAAE,OAAO,CAAA;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,kFAAkF;IAClF,WAAW,EAAE,OAAO,CAAA;IACpB,QAAQ,EAAE,YAAY,CAAA;IACtB,KAAK,EAAE,YAAY,CAAA;IACnB,wDAAwD;IACxD,KAAK,EAAE;QAAE,GAAG,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAA;IACtD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAA;IACzB,kFAAkF;IAClF,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,oEAAoE;AACpE,eAAO,MAAM,SAAS,QAAS,MAAM,KAAG,MAYvC,CAAA;AAED,+FAA+F;AAC/F,eAAO,MAAM,YAAY,YAAmB,MAAM,KAAG,OAAO,CAAC,OAAO,CAOhE,CAAA;AAmBJ,eAAO,MAAM,eAAe,QAAe,MAAM,KAAG,OAAO,CAAC,WAAW,CAoBtE,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,eAAe,WAAY,WAAW,KAAG,KAAK,CAAC,UAAU,GAAG,OAAO,CAG/E,CAAA;AAmBD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,WAAY,WAAW,KAAG,MAoFtD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAChB,MAAM,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC1C,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA+C7C,CAAA"}