@tacuchi/agent-workflow-cli 12.8.0 → 12.10.0

package/dist/application/source-launch-scripts-service.js

@@ -0,0 +1,302 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { detectStackDict } from "./stack-detect.js";
+const SECRET_RE = /(SECRET|TOKEN|PASSWORD|PASSWD|PWD|API[_-]?KEY|PRIVATE|CREDENTIAL)/i;
+const MARKER_RE = /^# agent-workflow:generated v\d+ sha256=([a-f0-9]+).*$/m;
+const MARKER_LINE_RE = /^# agent-workflow:generated v\d+ sha256=[a-f0-9]+.*\r?\n/m;
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function isSecretName(name) {
+    return SECRET_RE.test(name);
+}
+/** Detect the launch descriptor for a source by inspecting its files. Pure (read-only). */
+export async function detectLaunchDescriptor(fs, sourcePath, alias) {
+    const detected = await detectStackDict(fs, sourcePath);
+    const stack = stackKey(detected);
+    const { command, args } = await deriveCommand(fs, sourcePath, stack);
+    const { params, profiles } = await parseConfig(fs, sourcePath);
+    return { version: 1, source: alias, stack, cwd: sourcePath, command, args, params, profiles };
+}
+function stackKey(detected) {
+    const build = (detected.build ?? "").toLowerCase();
+    if (build === "maven")
+        return "maven";
+    if (build === "gradle")
+        return "gradle";
+    if (detected.framework === "Angular")
+        return "angular";
+    if (build === "npm")
+        return "npm";
+    return "unknown";
+}
+async function deriveCommand(fs, sourcePath, stack) {
+    switch (stack) {
+        case "npm": {
+            const script = await pickNpmScript(fs, sourcePath);
+            if (script === "start")
+                return { command: "npm", args: ["start"] };
+            if (script)
+                return { command: "npm", args: ["run", script] };
+            return { command: null, args: [] };
+        }
+        case "angular":
+            return { command: "npm", args: ["start"] };
+        case "gradle": {
+            const wrapper = (await fs.exists(join(sourcePath, "gradlew"))) ? "./gradlew" : "gradle";
+            return { command: wrapper, args: ["bootRun"] };
+        }
+        case "maven": {
+            const wrapper = (await fs.exists(join(sourcePath, "mvnw"))) ? "./mvnw" : "mvn";
+            return { command: wrapper, args: ["spring-boot:run"] };
+        }
+        default:
+            return { command: null, args: [] };
+    }
+}
+/** Prefer a `dev` script, then `start`; null when package.json has neither. */
+async function pickNpmScript(fs, sourcePath) {
+    try {
+        const pkg = JSON.parse(await fs.readText(join(sourcePath, "package.json")));
+        const scripts = pkg.scripts ?? {};
+        if (scripts.dev)
+            return "dev";
+        if (scripts.start)
+            return "start";
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse `.env*` (and detect Spring `application-<profile>.*`) into params + profiles. */
+async function parseConfig(fs, sourcePath) {
+    let entries = [];
+    try {
+        entries = await fs.list(sourcePath);
+    }
+    catch {
+        return { params: [], profiles: [] };
+    }
+    const names = entries.map((e) => e.name);
+    const profiles = detectProfiles(names);
+    // Params: union of keys across `.env` and `.env.<profile>` files; default from base `.env`.
+    const params = new Map();
+    const envFiles = names.filter((n) => n === ".env" || /^\.env\.[A-Za-z0-9_-]+$/.test(n));
+    for (const file of envFiles) {
+        let content;
+        try {
+            content = await fs.readText(join(sourcePath, file));
+        }
+        catch {
+            continue;
+        }
+        mergeEnvParams(params, parseEnv(content), file === ".env");
+    }
+    return {
+        params: [...params.values()].sort((a, b) => a.name.localeCompare(b.name)),
+        profiles: profiles.sort(),
+    };
+}
+/** Profiles from `.env.<profile>` (excluding `.env.local`) and `application-<profile>.{yml,yaml,properties}`. */
+function detectProfiles(names) {
+    const profiles = new Set();
+    for (const name of names) {
+        const envProfile = /^\.env\.([A-Za-z0-9_-]+)$/.exec(name)?.[1];
+        if (envProfile && envProfile !== "local")
+            profiles.add(envProfile);
+        const springProfile = /^application-([A-Za-z0-9_-]+)\.(ya?ml|properties)$/.exec(name)?.[1];
+        if (springProfile)
+            profiles.add(springProfile);
+    }
+    return [...profiles];
+}
+/** Merge one env file's pairs into the param map; the base `.env` supplies defaults. */
+function mergeEnvParams(params, pairs, isBase) {
+    for (const [key, value] of pairs) {
+        const existing = params.get(key);
+        if (!existing) {
+            params.set(key, { name: key, default: isBase ? value : "", secret: isSecretName(key) });
+        }
+        else if (isBase && existing.default === "") {
+            existing.default = value;
+        }
+    }
+}
+function parseEnv(content) {
+    const out = [];
+    for (const raw of content.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let value = line.slice(eq + 1).trim();
+        // Strip surrounding quotes; never carry a secret's value into the descriptor.
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out.push([key, isSecretName(key) ? "" : value]);
+    }
+    return out;
+}
+// --- Rendering -------------------------------------------------------------
+/**
+ * Assemble a generated script with a self-describing hash marker. The recorded
+ * hash covers the whole file EXCEPT the marker line itself (a line cannot hash
+ * its own value), so regeneration can detect user edits to any other line.
+ */
+function withMarker(beforeMarker, afterMarker) {
+    const hashed = `${[...beforeMarker, ...afterMarker].join("\n")}\n`;
+    const marker = `# agent-workflow:generated v1 sha256=${sha256(hashed)}`;
+    return `${[...beforeMarker, marker, ...afterMarker].join("\n")}\n`;
+}
+function humanHeader(desc) {
+    return [
+        `# Lanzamiento directo de ${desc.source} (${desc.stack}).`,
+        "# Editá libremente debajo: agent-workflow NO re-genera scripts que hayas editado.",
+    ];
+}
+export function renderLaunchJson(desc) {
+    const hash = sha256(JSON.stringify(desc, null, 2));
+    const withMeta = { ...desc, _generated: { version: 1, sha256: hash } };
+    return `${JSON.stringify(withMeta, null, 2)}\n`;
+}
+export function renderRunSh(desc) {
+    const after = [
+        ...humanHeader(desc),
+        "set -euo pipefail",
+        `cd "${desc.cwd}"`,
+        'PROFILE="${1:-}"',
+        'if [ -n "$PROFILE" ] && [ -f ".env.$PROFILE" ]; then set -a; . "./.env.$PROFILE"; set +a; fi',
+    ];
+    for (const p of desc.params) {
+        after.push(`export ${p.name}="\${${p.name}:-${shEscape(p.default)}}"`);
+    }
+    if (desc.command) {
+        after.push(`exec ${desc.command} ${desc.args.map(shQuote).join(" ")}`.trimEnd());
+    }
+    else {
+        after.push(`echo "No se detectó comando de arranque para ${desc.source}. Completá este script." >&2`);
+        after.push("exit 1");
+    }
+    return withMarker(["#!/usr/bin/env bash"], after);
+}
+export function renderRunPs1(desc) {
+    const after = [
+        ...humanHeader(desc),
+        'param([string]$Profile = "")',
+        "$ErrorActionPreference = 'Stop'",
+        `Set-Location "${desc.cwd}"`,
+        'if ($Profile -and (Test-Path ".env.$Profile")) { Get-Content ".env.$Profile" | ForEach-Object { if ($_ -match "^\\s*([^#=]+)=(.*)$") { [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim()) } } }',
+    ];
+    for (const p of desc.params) {
+        after.push(`if (-not $env:${p.name}) { $env:${p.name} = "${ps1Escape(p.default)}" }`);
+    }
+    if (desc.command) {
+        after.push(`& ${ps1Quote(desc.command)} ${desc.args.map(ps1Quote).join(" ")}`.trimEnd());
+    }
+    else {
+        after.push(`Write-Error "No se detectó comando de arranque para ${desc.source}. Completá este script."`);
+        after.push("exit 1");
+    }
+    return withMarker([], after);
+}
+function shEscape(v) {
+    return v.replace(/(["\\$`])/g, "\\$1");
+}
+function shQuote(v) {
+    return /^[A-Za-z0-9_./:-]+$/.test(v) ? v : `'${v.replace(/'/g, "'\\''")}'`;
+}
+function ps1Escape(v) {
+    return v.replace(/`/g, "``").replace(/"/g, '`"');
+}
+function ps1Quote(v) {
+    return /^[A-Za-z0-9_./:-]+$/.test(v) ? v : `"${ps1Escape(v)}"`;
+}
+/**
+ * Write `content` to `path` only if the on-disk file is still pristine (its
+ * recorded hash matches its current body). A user-edited file is preserved.
+ * `extractRecorded` returns the recorded hash + the hash of the current body,
+ * or null when the file has no marker (treated as user-owned → preserved).
+ */
+async function writeIfPristine(fs, path, content, recompute) {
+    if (!(await fs.exists(path))) {
+        await fs.writeText(path, content);
+        return "created";
+    }
+    const existing = await fs.readText(path);
+    const check = recompute(existing);
+    if (check && check.recorded === check.actual) {
+        await fs.writeText(path, content);
+        return "regenerated";
+    }
+    return "preserved";
+}
+function shellRecompute(existing) {
+    const m = MARKER_RE.exec(existing);
+    if (!m)
+        return null;
+    const recorded = m[1];
+    // Hash covers the whole file minus the marker line (symmetric with withMarker).
+    const withoutMarker = existing.replace(MARKER_LINE_RE, "");
+    return { recorded, actual: sha256(withoutMarker) };
+}
+function jsonRecompute(existing) {
+    try {
+        const parsed = JSON.parse(existing);
+        const recorded = parsed._generated?.sha256;
+        if (typeof recorded !== "string")
+            return null;
+        const { _generated, ...rest } = parsed;
+        return { recorded, actual: sha256(JSON.stringify(rest, null, 2)) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Generate (idempotently) the descriptor + per-OS scripts for one source. */
+export async function generateSourceLaunchArtifacts(fs, toolsDir, sourcePath, alias) {
+    const desc = await detectLaunchDescriptor(fs, sourcePath, alias);
+    const dir = join(toolsDir, alias);
+    await fs.mkdirp(dir);
+    const launchJson = await writeIfPristine(fs, join(dir, "launch.json"), renderLaunchJson(desc), jsonRecompute);
+    const runSh = await writeIfPristine(fs, join(dir, "run.sh"), renderRunSh(desc), shellRecompute);
+    const runPs1 = await writeIfPristine(fs, join(dir, "run.ps1"), renderRunPs1(desc), shellRecompute);
+    return {
+        alias,
+        stack: desc.stack,
+        launchable: desc.command !== null,
+        outcomes: { launchJson, runSh, runPs1 },
+    };
+}
+/**
+ * Generate launch artifacts for every source under `toolsDir/<alias>/`. Degrades
+ * cleanly: with the `tools` capability off, nothing is generated (and it says so);
+ * a source whose path is missing is skipped rather than producing junk.
+ */
+export async function generateLaunchArtifacts(fs, toolsDir, sources, toolsEnabled) {
+    if (!toolsEnabled) {
+        return {
+            toolsRole: "off",
+            generated: [],
+            skipped: sources.map((s) => ({ alias: s.alias, reason: "tools_role_off" })),
+        };
+    }
+    const generated = [];
+    const skipped = [];
+    for (const s of sources) {
+        if (!(await fs.exists(s.path))) {
+            skipped.push({ alias: s.alias, reason: "path_not_found" });
+            continue;
+        }
+        generated.push(await generateSourceLaunchArtifacts(fs, toolsDir, s.path, s.alias));
+    }
+    return { toolsRole: "enabled", generated, skipped };
+}
+//# sourceMappingURL=source-launch-scripts-service.js.map

package/dist/application/source-launch-scripts-service.js.map

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

package/dist/application/source-launch-service.d.ts

@@ -0,0 +1,52 @@
+import type { FileSystemPort } from "../ports/file-system.js";
+import type { ProcessPort } from "../ports/process.js";
+import type { PathsService } from "./paths-service.js";
+import { type ProcessRecord } from "./process-registry-service.js";
+import type { LaunchDescriptor } from "./source-launch-scripts-service.js";
+export interface LaunchRequest {
+    alias: string;
+    profile: string | null;
+    /** param name → value entered by the user (overrides the descriptor default). */
+    values: Record<string, string>;
+}
+export interface ResolvedLaunch {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    logPath: string;
+}
+export interface LaunchDeps {
+    fs: FileSystemPort;
+    proc: ProcessPort;
+    paths: PathsService;
+    /** Base environment the child inherits (the caller passes the real process env). */
+    baseEnv: Record<string, string>;
+    /** Injected clock for deterministic tests; defaults to the wall clock. */
+    now?: () => string;
+}
+export type LaunchResult = {
+    ok: true;
+    record: ProcessRecord;
+} | {
+    ok: false;
+    error: "no_descriptor" | "not_launchable" | "spawn_failed";
+    message: string;
+};
+/** Read a source's launch descriptor, or null when absent/corrupt. */
+export declare function readDescriptor(fs: FileSystemPort, workspaceDir: string, alias: string): Promise<LaunchDescriptor | null>;
+/** Log file for a source+profile, under docs/logs/. */
+export declare function logFileFor(logsDir: string, alias: string, profile: string | null): string;
+/** Resolve the concrete command/args/env/cwd/log for a launch. Null if the descriptor has no command. */
+export declare function resolveLaunch(desc: LaunchDescriptor, req: LaunchRequest, logsDir: string, baseEnv: Record<string, string>): ResolvedLaunch | null;
+/** A running process for the same source+profile, if any (collision). */
+export declare function findCollision(processes: ProcessRecord[], alias: string, profile: string | null): ProcessRecord | undefined;
+/** Launch a source detached: resolve → open log dir → spawnDetached → register. */
+export declare function launchSource(deps: LaunchDeps, req: LaunchRequest): Promise<LaunchResult>;
+/** Stop a process (kill its tree) and mark it stopped in the registry. */
+export declare function stopProcess(deps: LaunchDeps, record: ProcessRecord): Promise<void>;
+/** Relaunch = stop the existing process, then launch the same source+profile afresh. */
+export declare function relaunchProcess(deps: LaunchDeps, record: ProcessRecord): Promise<LaunchResult>;
+/** Last `maxLines` of a process log (best-effort; empty when missing). */
+export declare function tailLog(fs: FileSystemPort, logPath: string, maxLines: number): Promise<string[]>;
+//# sourceMappingURL=source-launch-service.d.ts.map

package/dist/application/source-launch-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-launch-service.d.ts","sourceRoot":"","sources":["../../src/application/source-launch-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,KAAK,aAAa,EAA0B,MAAM,+BAA+B,CAAC;AAC3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,cAAc,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/F,sEAAsE;AACtE,wBAAsB,cAAc,CAClC,EAAE,EAAE,cAAc,EAClB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAQlC;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEzF;AAED,yGAAyG;AACzG,wBAAgB,aAAa,CAC3B,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,cAAc,GAAG,IAAI,CAcvB;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,aAAa,GAAG,SAAS,CAI3B;AAMD,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAyC9F;AAED,0EAA0E;AAC1E,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAGxF;AAED,wFAAwF;AACxF,wBAAsB,eAAe,CACnC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,0EAA0E;AAC1E,wBAAsB,OAAO,CAC3B,EAAE,EAAE,cAAc,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAUnB"}

package/dist/application/source-launch-service.js

@@ -0,0 +1,116 @@
+import { join } from "node:path";
+import { ProcessRegistryService } from "./process-registry-service.js";
+/** Read a source's launch descriptor, or null when absent/corrupt. */
+export async function readDescriptor(fs, workspaceDir, alias) {
+    const file = join(workspaceDir, "docs", "tools", alias, "launch.json");
+    if (!(await fs.exists(file)))
+        return null;
+    try {
+        return JSON.parse(await fs.readText(file));
+    }
+    catch {
+        return null;
+    }
+}
+/** Log file for a source+profile, under docs/logs/. */
+export function logFileFor(logsDir, alias, profile) {
+    return join(logsDir, profile ? `${alias}-${profile}.log` : `${alias}.log`);
+}
+/** Resolve the concrete command/args/env/cwd/log for a launch. Null if the descriptor has no command. */
+export function resolveLaunch(desc, req, logsDir, baseEnv) {
+    if (!desc.command)
+        return null;
+    const env = { ...baseEnv };
+    for (const p of desc.params) {
+        env[p.name] = req.values[p.name] ?? p.default;
+    }
+    if (req.profile)
+        env.PROFILE = req.profile;
+    return {
+        command: desc.command,
+        args: desc.args,
+        cwd: desc.cwd,
+        env,
+        logPath: logFileFor(logsDir, req.alias, req.profile),
+    };
+}
+/** A running process for the same source+profile, if any (collision). */
+export function findCollision(processes, alias, profile) {
+    return processes.find((p) => p.sourceAlias === alias && p.profile === profile && p.state === "running");
+}
+function registry(deps) {
+    return new ProcessRegistryService(deps.fs, deps.proc, deps.paths.cwdProcessesFile());
+}
+/** Launch a source detached: resolve → open log dir → spawnDetached → register. */
+export async function launchSource(deps, req) {
+    const desc = await readDescriptor(deps.fs, deps.paths.workspaceDir(), req.alias);
+    if (!desc)
+        return { ok: false, error: "no_descriptor", message: `Sin descriptor para ${req.alias}` };
+    const logsDir = deps.paths.cwdDocsLogsDir();
+    const resolved = resolveLaunch(desc, req, logsDir, deps.baseEnv);
+    if (!resolved) {
+        return {
+            ok: false,
+            error: "not_launchable",
+            message: `El descriptor de ${req.alias} no tiene comando de arranque`,
+        };
+    }
+    await deps.fs.mkdirp(logsDir);
+    try {
+        const { pid } = await deps.proc.spawnDetached(resolved.command, resolved.args, {
+            cwd: resolved.cwd,
+            env: resolved.env,
+            logPath: resolved.logPath,
+        });
+        const startedAt = (deps.now ?? (() => new Date().toISOString()))();
+        // Persist only NON-secret entered values so a relaunch can reuse them; secrets
+        // are never written to the registry.
+        const secretNames = new Set(desc.params.filter((p) => p.secret).map((p) => p.name));
+        const persistedValues = Object.fromEntries(Object.entries(req.values).filter(([k]) => !secretNames.has(k)));
+        const record = await registry(deps).register({
+            sourceAlias: req.alias,
+            profile: req.profile,
+            command: resolved.command,
+            args: resolved.args,
+            pid,
+            startedAt,
+            logPath: resolved.logPath,
+            values: persistedValues,
+        });
+        return { ok: true, record };
+    }
+    catch (err) {
+        return { ok: false, error: "spawn_failed", message: err.message };
+    }
+}
+/** Stop a process (kill its tree) and mark it stopped in the registry. */
+export async function stopProcess(deps, record) {
+    await deps.proc.killTree(record.pid);
+    await registry(deps).markStopped(record.id);
+}
+/** Relaunch = stop the existing process, then launch the same source+profile afresh. */
+export async function relaunchProcess(deps, record) {
+    await stopProcess(deps, record);
+    // Reuse the same profile + persisted non-secret values (secrets re-default to empty).
+    return launchSource(deps, {
+        alias: record.sourceAlias,
+        profile: record.profile,
+        values: record.values ?? {},
+    });
+}
+/** Last `maxLines` of a process log (best-effort; empty when missing). */
+export async function tailLog(fs, logPath, maxLines) {
+    if (!(await fs.exists(logPath)))
+        return [];
+    try {
+        const lines = (await fs.readText(logPath)).split(/\r?\n/);
+        // Drop only the trailing empty line from a final newline; keep interior blanks.
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        return lines.slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=source-launch-service.js.map

package/dist/application/source-launch-service.js.map

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

package/dist/application/workspace-init-service.d.ts

@@ -3,6 +3,7 @@ import type { FileSystemPort } from "../ports/file-system.js";
 import { type MultirootError, type MultirootResult } from "./multiroot-service.js";
 import { PathsService } from "./paths-service.js";
 import { type ProjectMdUpsertError, type ProjectMdUpsertOutput } from "./project-md-upsert-service.js";
+import { type LaunchArtifactsSummary } from "./source-launch-scripts-service.js";
 export interface WorkspaceSource {
     alias: string;
     path: string;
@@ -48,6 +49,8 @@ export interface WorkspaceInitResult {
     };
     /** Reconcile: detach of sources that were in the previous block and no longer are. */
     detached_removed?: MultirootResult | MultirootError;
+    /** Per-source launch descriptor + scripts generated under docs/tools/ (gated on the `tools` role). */
+    launch_artifacts: LaunchArtifactsSummary;
 }
 /**
  * Initialize the current directory as an agent-workflow **workspace**. Unifies the

package/dist/application/workspace-init-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-init-service.d.ts","sourceRoot":"","sources":["../../src/application/workspace-init-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAgB,MAAM,wBAAwB,CAAC;AAGjG,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE3B,MAAM,gCAAgC,CAAC;AAkBxC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,eAAe,CAAC;IAC1B,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,UAAU,EAAE,qBAAqB,GAAG,oBAAoB,CAAC;IACzD,+EAA+E;IAC/E,gBAAgB,EAAE,eAAe,GAAG,cAAc,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC;CACrD;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,cAAc,EAClB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,GAAG,uBAAuB,CAAC,CAmFxD"}
+{"version":3,"file":"workspace-init-service.d.ts","sourceRoot":"","sources":["../../src/application/workspace-init-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAgB,MAAM,wBAAwB,CAAC;AAGjG,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAE3B,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,oCAAoC,CAAC;AAuB5C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,eAAe,CAAC;IAC1B,WAAW,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,UAAU,EAAE,qBAAqB,GAAG,oBAAoB,CAAC;IACzD,+EAA+E;IAC/E,gBAAgB,EAAE,eAAe,GAAG,cAAc,GAAG;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,eAAe,GAAG,cAAc,CAAC;IACpD,sGAAsG;IACtG,gBAAgB,EAAE,sBAAsB,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,cAAc,EAClB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,GAAG,uBAAuB,CAAC,CAiGxD"}

package/dist/application/workspace-init-service.js

@@ -5,6 +5,8 @@ import { normalizePath } from "./multiroot/paths.js";
 import { parseProjectBlock } from "./parsers/project-block.js";
 import { PathsService } from "./paths-service.js";
 import { runProjectMdUpsertWrite, } from "./project-md-upsert-service.js";
+import { resolveSkills } from "./skills-resolver-service.js";
+import { generateLaunchArtifacts, } from "./source-launch-scripts-service.js";
 /** docs/ taxonomy scaffolded for every workspace (one folder per export category). */
 const DOCS_FOLDERS = [
     "specs",
@@ -17,6 +19,10 @@ const DOCS_FOLDERS = [
 ];
 /** Visibility files (machine-specific absolute roots) — gitignored when external sources exist. */
 const VISIBILITY_GITIGNORE = [".claude/settings.local.json", ".codex/config.toml"];
+/** Runtime artifacts of the source-launch feature — machine-specific, never committed. */
+function runtimeGitignoreEntries(ns) {
+    return [`.${ns}/processes.json`, "docs/logs/"];
+}
 const DEFAULT_MAIN_BRANCH = "main";
 /**
  * Initialize the current directory as an agent-workflow **workspace**. Unifies the
@@ -49,6 +55,12 @@ export async function runWorkspaceInit(fs, env, paths, input) {
     const targetEnv = workspace !== resolve(env.cwd()) ? overrideCwd(env, workspace) : env;
     const scaffold = await scaffoldDirs(fs, workspace, wsPaths);
     const skillsToml = await seedSkillsToml(fs, wsPaths);
+    // Runtime artifacts (process registry + launch logs) are machine-specific — gitignore always.
+    await ensureRuntimeGitignore(fs, workspace, wsPaths.namespace);
+    // Per-source launch artifacts under docs/tools/ (descriptor + run.sh/run.ps1),
+    // gated on the `tools` capability and idempotent (preserves user-edited scripts).
+    const skillsRes = await resolveSkills(fs, wsPaths);
+    const launchArtifacts = await generateLaunchArtifacts(fs, join(workspace, "docs", "tools"), sources.map((s) => ({ alias: s.alias, path: s.path })), skillsRes.skills.tools.enabled);
     // Previous sources (to detach removed ones) come from the same existing block.
     const previousPaths = (existing?.fuentes ?? []).map((f) => f.path).filter((p) => p.length > 0);
     const projectMd = await runProjectMdUpsertWrite(fs, targetEnv, wsPaths, {
@@ -79,6 +91,7 @@ export async function runWorkspaceInit(fs, env, paths, input) {
             skills_toml: skillsToml,
             project_md: projectMd,
             attach_multiroot: { skipped: true, reason: "project_md_failed" },
+            launch_artifacts: launchArtifacts,
         };
     }
     // Multi-root visibility only matters with 2+ sources. Single source → no-op.
@@ -93,6 +106,7 @@ export async function runWorkspaceInit(fs, env, paths, input) {
         project_md: projectMd,
         attach_multiroot: visibility.attach,
         ...(visibility.detached !== undefined ? { detached_removed: visibility.detached } : {}),
+        launch_artifacts: launchArtifacts,
     };
 }
 function plannedScaffold(workspace, ns) {
@@ -114,6 +128,11 @@ function buildDryRunResult(workspace, namespace, sources) {
         attach_multiroot: anyExternal
             ? { skipped: true, reason: "dry_run" }
             : { skipped: true, reason: "no_external_sources" },
+        launch_artifacts: {
+            toolsRole: "enabled",
+            generated: [],
+            skipped: sources.map((s) => ({ alias: s.alias, reason: "path_not_found" })),
+        },
     };
 }
 async function scaffoldDirs(fs, workspace, wsPaths) {
@@ -132,6 +151,15 @@ async function scaffoldDirs(fs, workspace, wsPaths) {
             await fs.writeText(keep, "");
         created.push(dir);
     }
+    // Runtime launch logs — created (no .gitkeep: the folder is gitignored).
+    const logsDir = join(workspace, "docs", "logs");
+    if (await fs.exists(logsDir)) {
+        existing.push(logsDir);
+    }
+    else {
+        await fs.mkdirp(logsDir);
+        created.push(logsDir);
+    }
     return { created, existing };
 }
 /** Seed `.workflow/skills.toml` with a commented template. Never clobbers an existing file. */
@@ -240,21 +268,29 @@ function resolveProyecto(arg, existing, workspace) {
         return existing.trim();
     return basename(workspace);
 }
-/** Ensure the workspace `.gitignore` ignores the visibility files (idempotent). */
-async function ensureVisibilityGitignore(fs, workspace) {
+/** Append any missing entries under a header to the workspace `.gitignore` (idempotent). */
+async function appendGitignoreEntries(fs, workspace, header, entries) {
     const file = join(workspace, ".gitignore");
     const existing = (await fs.exists(file)) ? await fs.readText(file) : "";
     const present = new Set(existing
         .split(/\r?\n/)
         .map((l) => l.trim())
         .filter((l) => l.length > 0));
-    const missing = VISIBILITY_GITIGNORE.filter((e) => !present.has(e));
+    const missing = entries.filter((e) => !present.has(e));
     if (missing.length === 0)
         return;
-    const block = `# Multi-root visibility (machine-specific paths — do not commit)\n${missing.join("\n")}\n`;
+    const block = `${header}\n${missing.join("\n")}\n`;
     const body = existing.replace(/\s+$/, "");
     await fs.writeText(file, body.length === 0 ? block : `${body}\n\n${block}`);
 }
+/** Ensure the workspace `.gitignore` ignores the visibility files (idempotent). */
+async function ensureVisibilityGitignore(fs, workspace) {
+    await appendGitignoreEntries(fs, workspace, "# Multi-root visibility (machine-specific paths — do not commit)", VISIBILITY_GITIGNORE);
+}
+/** Ensure the workspace `.gitignore` ignores source-launch runtime artifacts (idempotent, always). */
+async function ensureRuntimeGitignore(fs, workspace, ns) {
+    await appendGitignoreEntries(fs, workspace, "# agent-workflow runtime (machine-specific — do not commit)", runtimeGitignoreEntries(ns));
+}
 function validateSources(sources) {
     if (!sources || sources.length < 1) {
         return {