specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/missions/runtime/mission-session-projector.js

@@ -4,6 +4,7 @@ exports.MissionSessionProjector = void 0;
 const desktop_db_1 = require("../../../desktop-db");
 const result_event_1 = require("../../accounting/runtime/result-event");
 const agent_store_1 = require("../../agents/runtime/agent-store");
+const audit_1 = require("../../audit");
 const agent_session_store_1 = require("./agent-session-store");
 /**
  * Missions' ProjectionSink: persists what happens in a mission's Core session
@@ -16,40 +17,54 @@ class MissionSessionProjector {
     conversationId;
     deps;
     background = new Map();
-    constructor(conversationId, deps) {
+    coreSessionId;
+    surface;
+    /** Extra fields on every broadcast of a non-mission session (the client tells them apart). */
+    tag;
+    missionSession;
+    constructor(conversationId, deps, projection = {}) {
         this.conversationId = conversationId;
         this.deps = deps;
+        this.coreSessionId = projection.coreSessionId ?? conversationId;
+        this.surface = projection.surface ?? 'agent-chat';
+        this.missionSession = this.coreSessionId === conversationId || projection.mission === true;
+        this.tag = this.missionSession ? {} : { coreSessionId: this.coreSessionId };
     }
     cursor(_sessionId) {
-        return (0, agent_session_store_1.getSessionCursor)(this.deps.db, this.conversationId)?.lastSeq ?? 0;
+        return (0, agent_session_store_1.getSessionCursor)(this.deps.db, this.conversationId, this.coreSessionId)?.lastSeq ?? 0;
     }
     apply(_sessionId, seq, ops) {
         const conversationId = this.conversationId;
         const outbox = [];
         const timestamp = new Date().toISOString();
         let processEnded = false;
+        const audited = [];
         this.deps.db.transaction(() => {
             for (const op of ops) {
                 switch (op.kind) {
                     case 'resident.phase': {
-                        const before = (0, agent_session_store_1.getSessionCursor)(this.deps.db, conversationId);
-                        (0, agent_session_store_1.setResidentState)(this.deps.db, conversationId, op.phase, op.processAlive, op.liveSubagents);
+                        const before = (0, agent_session_store_1.getSessionCursor)(this.deps.db, conversationId, this.coreSessionId);
+                        (0, agent_session_store_1.setResidentState)(this.deps.db, conversationId, op.phase, op.processAlive, op.liveSubagents, this.coreSessionId);
                         if (before?.processAlive && !op.processAlive)
                             processEnded = true;
-                        outbox.push({ type: 'agent_resident_state', conversationId, phase: op.phase, liveSubagents: op.liveSubagents, processAlive: op.processAlive, timestamp });
+                        // The conversation's state across its sessions: a Flow's sub-agents are the mission's while in Flow.
+                        const state = (0, agent_session_store_1.conversationSessionState)(this.deps.db, conversationId);
+                        outbox.push({ type: 'agent_resident_state', conversationId, phase: state?.residentPhase ?? op.phase, liveSubagents: state?.liveSubagents ?? op.liveSubagents, processAlive: state?.processAlive ?? op.processAlive, ...this.tag, timestamp });
                         break;
                     }
                     case 'turn.opened':
                         if (op.origin === 'user')
                             break;
                         this.background.set(op.turnId, { origin: op.origin, triggeredBy: op.triggeredBy, startedAt: op.at });
-                        outbox.push({ type: 'agent_turn_started', conversationId, turnId: op.turnId, origin: op.origin, triggeredBy: op.triggeredBy, timestamp });
+                        outbox.push({ type: 'agent_turn_started', conversationId, turnId: op.turnId, origin: op.origin, triggeredBy: op.triggeredBy, ...this.tag, timestamp });
                         break;
                     case 'turn.delta':
                         if (op.channel === 'text' && this.background.has(op.turnId))
                             outbox.push({ type: 'agent_stream', conversationId, turnId: op.turnId, delta: op.delta, timestamp });
                         break;
                     case 'turn.tool':
+                        if (op.tool.phase === 'started')
+                            audited.push({ name: op.tool.name, input: op.tool.input, role: 'mission' });
                         if (!this.background.has(op.turnId))
                             break;
                         outbox.push(op.tool.phase === 'started'
@@ -65,35 +80,39 @@ class MissionSessionProjector {
                         if (!conversation)
                             break;
                         // A journal replay (projection rebuild) must not record a turn twice.
-                        if ((0, agent_session_store_1.isCoreTurnRecorded)(this.deps.db, conversationId, op.turnId)) {
-                            outbox.push({ type: 'agent_turn_done', conversationId, turnId: op.turnId, origin: turn.origin, status: op.status, triggeredBy: turn.triggeredBy, timestamp });
+                        if ((0, agent_session_store_1.isCoreTurnRecorded)(this.deps.db, conversationId, op.turnId, this.coreSessionId)) {
+                            outbox.push({ type: 'agent_turn_done', conversationId, turnId: op.turnId, origin: turn.origin, status: op.status, triggeredBy: turn.triggeredBy, ...this.tag, timestamp });
                             break;
                         }
                         const message = op.text.trim()
                             ? (0, agent_store_1.addAgentMessage)(this.deps.db, { conversationId, role: 'assistant', content: op.text, turnOrigin: turn.origin, coreTurnId: op.turnId })
                             : null;
-                        this.recordInvocation(conversation, { id: (0, agent_session_store_1.coreTurnInvocationId)(conversation.id, op.turnId), providerId: conversation.provider, model: null, usage: op.usage, status: op.status, origin: turn.origin, startedAt: turn.startedAt, finishedAt: op.at });
-                        outbox.push({ type: 'agent_turn_done', conversationId, turnId: op.turnId, origin: turn.origin, status: op.status, triggeredBy: turn.triggeredBy, fullText: op.text, ...(message ? { messageId: message.id } : {}), timestamp });
+                        this.recordInvocation(conversation, { id: (0, agent_session_store_1.coreTurnInvocationId)(conversation.id, op.turnId, this.coreSessionId), providerId: conversation.provider, model: null, usage: op.usage, status: op.status, origin: turn.origin, startedAt: turn.startedAt, finishedAt: op.at });
+                        outbox.push({ type: 'agent_turn_done', conversationId, turnId: op.turnId, origin: turn.origin, status: op.status, triggeredBy: turn.triggeredBy, fullText: op.text, ...(message ? { messageId: message.id } : {}), ...this.tag, timestamp });
                         if (conversation.pinned_project_id)
                             outbox.push({ type: 'spending.invalidated', projectId: conversation.pinned_project_id });
                         break;
                     }
                     case 'subagent.upsert':
-                        (0, agent_session_store_1.upsertSubagent)(this.deps.db, conversationId, op.subagent);
-                        outbox.push({ type: 'agent_subagent', conversationId, subagent: op.subagent, timestamp });
+                        (0, agent_session_store_1.upsertSubagent)(this.deps.db, conversationId, op.subagent, this.coreSessionId);
+                        outbox.push({ type: 'agent_subagent', conversationId, subagent: op.subagent, ...this.tag, timestamp });
                         break;
                     case 'subagent.output':
                         if (!this.subagentKnown(op.subagentId))
                             break;
+                        if (op.tool?.phase === 'started')
+                            audited.push({ name: op.tool.name, input: op.tool.input, role: 'subagent' });
                         (0, agent_session_store_1.appendSubagentEvent)(this.deps.db, conversationId, op.subagentId, op.seq, op.channel, op.delta, op.tool);
-                        outbox.push({ type: 'agent_subagent_event', conversationId, subagentId: op.subagentId, seq: op.seq, channel: op.channel, ...(op.delta !== null ? { delta: op.delta } : {}), ...(op.tool ? { tool: op.tool } : {}), timestamp });
+                        outbox.push({ type: 'agent_subagent_event', conversationId, subagentId: op.subagentId, seq: op.seq, channel: op.channel, ...(op.delta !== null ? { delta: op.delta } : {}), ...(op.tool ? { tool: op.tool } : {}), ...this.tag, timestamp });
                         break;
                     case 'subagent.billed': {
                         // A delegated sub-agent's own spend: recorded once (deterministic id), on top of the parent's.
                         const conversation = (0, agent_store_1.getAgentConversation)(this.deps.db, conversationId);
                         if (!conversation)
                             break;
-                        const invocationId = `core-subagent:${conversationId}:${op.subagentId}:${op.seq}`;
+                        const invocationId = this.coreSessionId === conversationId
+                            ? `core-subagent:${conversationId}:${op.subagentId}:${op.seq}`
+                            : `core-subagent:${conversationId}:${this.coreSessionId}:${op.subagentId}:${op.seq}`;
                         if (this.deps.db.prepare('SELECT 1 FROM agent_invocations WHERE id = ?').get(invocationId))
                             break;
                         const startedAt = this.subagentStartedAt(op.subagentId) ?? op.at;
@@ -103,10 +122,10 @@ class MissionSessionProjector {
                         break;
                     }
                     case 'session.updated':
-                        outbox.push({ type: 'agent_session_updated', conversationId, outcome: op.outcome, changes: op.changes, timestamp });
+                        outbox.push({ type: 'agent_session_updated', conversationId, outcome: op.outcome, changes: op.changes, ...this.tag, timestamp });
                         break;
                     case 'notice':
-                        outbox.push({ type: 'agent_session_notice', conversationId, level: op.level, code: op.code, message: op.message, timestamp });
+                        outbox.push({ type: 'agent_session_notice', conversationId, level: op.level, code: op.code, message: op.message, ...this.tag, timestamp });
                         break;
                     case 'provider.ref':
                     case 'input.state':
@@ -115,15 +134,32 @@ class MissionSessionProjector {
                         break;
                 }
             }
-            (0, agent_session_store_1.advanceSessionCursor)(this.deps.db, conversationId, seq);
+            (0, agent_session_store_1.advanceSessionCursor)(this.deps.db, conversationId, seq, this.coreSessionId);
         })();
         for (const message of outbox)
             this.deps.broadcast(message);
-        if (processEnded)
+        if (audited.length > 0)
+            this.recordAudit(audited);
+        // The mission's capability belongs to its own resident process only.
+        if (processEnded && this.missionSession)
             this.deps.onProcessEnded?.(conversationId);
     }
+    /** After commit: the audit observes; it never joins the projection transaction. */
+    recordAudit(tools) {
+        try {
+            if (!this.deps.agentAudit)
+                return;
+            const projectId = (0, agent_store_1.getAgentConversation)(this.deps.db, this.conversationId)?.pinned_project_id;
+            const recorder = projectId ? this.deps.agentAudit(projectId) : null;
+            if (!recorder)
+                return;
+            for (const tool of tools)
+                (0, audit_1.recordToolCall)(recorder, { runId: this.conversationId, role: tool.role, source: 'core-session' }, tool.name, tool.input);
+        }
+        catch { /* audit is observing only */ }
+    }
     subagentKnown(subagentId) {
-        return !!this.deps.db.prepare('SELECT 1 FROM agent_subagents WHERE conversation_id = ? AND subagent_id = ?').get(this.conversationId, subagentId);
+        return !!this.deps.db.prepare('SELECT 1 FROM agent_subagents WHERE conversation_id = ? AND subagent_id = ? AND core_session_id = ?').get(this.conversationId, subagentId, this.coreSessionId);
     }
     subagentStartedAt(subagentId) {
         const row = this.deps.db.prepare('SELECT started_at FROM agent_subagents WHERE conversation_id = ? AND subagent_id = ?').get(this.conversationId, subagentId);
@@ -161,6 +197,7 @@ class MissionSessionProjector {
             finished_at: invocation.finishedAt,
             total_cost_usd_estimated: estimated,
             origin: invocation.origin,
+            surface: this.surface,
             ...result,
         });
     }

package/server/dist/modules/missions/runtime/mission-tool-policy.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.missionSpawnPolicy = missionSpawnPolicy;
+exports.missionReadOnlyGap = missionReadOnlyGap;
+exports.missionSessionBoundary = missionSessionBoundary;
+exports.isReadOnlySessionBoundary = isReadOnlySessionBoundary;
+const feature_flags_1 = require("../../../feature-flags");
+const runtime_1 = require("../../../providers/runtime");
+/**
+ * Spawn options for a legacy (one-shot or native live) mission turn. Providers
+ * without a native read-only mode (Kimi prompt mode) keep their default tools:
+ * a mission must still work, and prompt-only guidance is not a boundary.
+ */
+function missionSpawnPolicy(adapter) {
+    if (!(0, feature_flags_1.isMissionReadOnlyEnabled)() || !(0, runtime_1.supportsToolPolicy)(adapter, 'read-only'))
+        return {};
+    return { toolPolicy: 'read-only', retainMcpTools: true };
+}
+/** The reason a provider's mission turns stay write-capable, or null when read-only. */
+function missionReadOnlyGap(adapter) {
+    if (!(0, feature_flags_1.isMissionReadOnlyEnabled)())
+        return 'disabled';
+    return (0, runtime_1.supportsToolPolicy)(adapter, 'read-only') ? null : 'unsupported';
+}
+/**
+ * Permission and tool fields of a mission's Core session policy. Uses the
+ * adapter's declared read-only session mapping when the Core driver can
+ * enforce it; otherwise keeps the legacy mapping (`sessionPermissions`).
+ * A tool restriction is only requested from a driver with `toolFiltering`,
+ * because Core refuses an unenforceable policy instead of ignoring it.
+ */
+function missionSessionBoundary(adapter, driver) {
+    const legacy = { permissions: adapter.capabilities.sessionPermissions ?? 'workspace-write' };
+    const readOnly = adapter.capabilities.missionReadOnlySession;
+    if (!(0, feature_flags_1.isMissionReadOnlyEnabled)() || !readOnly)
+        return legacy;
+    if (readOnly.tools === 'read-only' && driver?.capabilities.toolFiltering !== true)
+        return legacy;
+    return {
+        permissions: readOnly.permissions,
+        ...(readOnly.tools === 'read-only' ? { tools: { mode: 'read-only' } } : {}),
+    };
+}
+/** True when a session boundary actually prevents workspace writes. */
+function isReadOnlySessionBoundary(boundary) {
+    return boundary.permissions === 'read-only' || boundary.tools?.mode === 'read-only';
+}

package/server/dist/modules/onboarding/adapters/http.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOnboardingRoutes = registerOnboardingRoutes;
+const application_1 = require("../application");
+const domain_1 = require("../domain");
+function sendError(res, err) {
+    if (err instanceof domain_1.SampleError) {
+        res.status(err.status).json({ error: err.code, detail: err.message });
+        return;
+    }
+    console.error('[onboarding] sample error:', err);
+    res.status(500).json({ error: 'sample_failed', detail: 'Unexpected error while handling the sample project' });
+}
+function text(value) {
+    return typeof value === 'string' && value.trim().length > 0 && value.length <= 1024 ? value.trim() : undefined;
+}
+/**
+ * Sample-project first run, mounted on the app-level `/api` router:
+ *   GET    /api/onboarding/sample   catalog, current sample, default folder and launch readiness
+ *   POST   /api/onboarding/sample   create (idempotent) + register the sample project
+ *   DELETE /api/onboarding/sample   unregister it; `?deleteFolder=1` also deletes the folder
+ * The run itself uses the ordinary rail launch route with the preset returned here.
+ */
+function registerOnboardingRoutes(router, deps) {
+    router.get('/onboarding/sample', async (req, res) => {
+        try {
+            const refresh = req.query.refresh === '1';
+            let readiness;
+            try {
+                readiness = (0, domain_1.chooseSamplePreset)(await deps.providers({ refresh }));
+            }
+            catch (err) {
+                // Detection failing is "not ready" (the recorded run is offered), never a 500.
+                console.warn('[onboarding] provider readiness failed:', err);
+                readiness = { ready: false, reason: 'no_provider', preset: null, localPreset: null };
+            }
+            const current = (0, application_1.currentSample)(deps);
+            res.json({
+                catalog: deps.samples.map((sample) => ({ id: sample.id, name: sample.name, specCount: sample.specs.length })),
+                sample: current ? { sampleId: current.record.sampleId, projectId: current.record.projectId, path: current.record.path, specIds: current.record.specIds } : null,
+                defaultParentDir: (0, application_1.defaultSampleParent)(deps.files),
+                launch: { ...readiness, estimate: domain_1.SAMPLE_ESTIMATE, runCapUsd: domain_1.SAMPLE_RUN_CAP_USD },
+            });
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    router.post('/onboarding/sample', async (req, res) => {
+        const body = (req.body ?? {});
+        try {
+            const result = await (0, application_1.createSample)(deps, {
+                sampleId: text(body.sampleId) ?? deps.samples[0]?.id ?? '',
+                locale: (0, domain_1.normalizeSampleLocale)(body.locale),
+                targetPath: text(body.path),
+                parentDir: text(body.parentDir),
+            });
+            res.status(result.reused ? 200 : 201).json({
+                reused: result.reused,
+                project: { id: result.project.id, name: result.project.name, path: result.project.path },
+                sample: { sampleId: result.record.sampleId, projectId: result.record.projectId, path: result.record.path, specIds: result.record.specIds },
+            });
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+    router.delete('/onboarding/sample', (req, res) => {
+        const body = (req.body ?? {});
+        try {
+            const result = (0, application_1.removeSample)(deps, { deleteFolder: req.query.deleteFolder === '1' || body.deleteFolder === true });
+            res.json({ ok: true, ...result });
+        }
+        catch (err) {
+            sendError(res, err);
+        }
+    });
+}

package/server/dist/modules/onboarding/adapters/providers.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presetCandidates = presetCandidates;
+exports.loadPresetCandidates = loadPresetCandidates;
+const provider_detection_1 = require("../../../provider-detection");
+const providers_1 = require("../../../providers");
+const local_adapter_1 = require("../../../providers/local-adapter");
+const pricing_1 = require("../../accounting/runtime/pricing");
+const spec_models_1 = require("../../specs/runtime/spec-models");
+/**
+ * The machine's providers as the preset chooser sees them: usable/auth state
+ * from the app-level detection snapshot, models and their rate-card price from
+ * the provider catalog. Local engines carry their discovered models and no price.
+ */
+function presetCandidates(snapshot) {
+    const candidates = [];
+    for (const adapter of (0, providers_1.listAdapters)()) {
+        const row = snapshot.providers[adapter.id];
+        if (!row || !(0, providers_1.hasAdapter)(adapter.id))
+            continue;
+        const local = (0, local_adapter_1.isLocalAdapter)(adapter);
+        const models = local
+            ? (row.models ?? []).map((value) => ({ value, priceUsdPer1M: null }))
+            : (0, spec_models_1.getModelsForProvider)(adapter.id).map(({ value }) => {
+                const price = (0, pricing_1.resolvePriceEntry)(adapter.id, value);
+                return { value, priceUsdPer1M: price ? price.inputPer1M + price.outputPer1M : null };
+            });
+        candidates.push({
+            id: adapter.id,
+            local,
+            usable: row.usable === true,
+            authState: row.authState,
+            defaultModel: (0, providers_1.getAdapter)(adapter.id).defaultModel(),
+            models,
+        });
+    }
+    return candidates;
+}
+async function loadPresetCandidates(refresh = false) {
+    return presetCandidates(await (0, provider_detection_1.getDetectionSnapshot)(refresh ? { refresh: true } : undefined));
+}

package/server/dist/modules/onboarding/adapters/runtime.js

@@ -0,0 +1,130 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSampleFiles = createSampleFiles;
+exports.createSampleGit = createSampleGit;
+exports.createSampleSpecs = createSampleSpecs;
+exports.createSampleState = createSampleState;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const worktree_manager_1 = require("../../../worktree-manager");
+const ticket_store_1 = require("../../specs/runtime/ticket-store");
+const domain_1 = require("../domain");
+/** Filesystem adapter (real disk; `home` is injectable for tests). */
+function createSampleFiles(home = os_1.default.homedir) {
+    const resolve = (target) => {
+        const absolute = path_1.default.resolve(target);
+        try {
+            return fs_1.default.realpathSync(absolute);
+        }
+        catch {
+            // A path that does not exist yet: resolve its nearest existing ancestor so
+            // a symlinked parent (macOS /var -> /private/var) compares like the home dir.
+            const parent = path_1.default.dirname(absolute);
+            if (parent === absolute)
+                return absolute;
+            return path_1.default.join(resolve(parent), path_1.default.basename(absolute));
+        }
+    };
+    return {
+        homeDir: () => home(),
+        join: (...parts) => path_1.default.join(...parts),
+        sep: path_1.default.sep,
+        resolve,
+        exists: (target) => fs_1.default.existsSync(target),
+        writeTree(root, files) {
+            for (const [relative, content] of Object.entries(files)) {
+                const file = path_1.default.join(root, ...relative.split('/'));
+                fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+                fs_1.default.writeFileSync(file, content, 'utf-8');
+            }
+        },
+        remove: (target) => fs_1.default.rmSync(target, { recursive: true, force: true }),
+        isGitRepo: (target) => fs_1.default.existsSync(path_1.default.join(target, '.git')),
+    };
+}
+/** git adapter: `init -b main` + one commit with a fixed, machine-independent identity. */
+function createSampleGit(git = worktree_manager_1.defaultGitRunner) {
+    const identity = ['-c', 'user.name=Specrails Sample', '-c', 'user.email=sample@specrails.invalid', '-c', 'commit.gpgsign=false'];
+    const must = async (args, cwd) => {
+        const result = await git.run(args, cwd);
+        if (result.code !== 0)
+            throw new Error((result.stderr || result.stdout || `git ${args[0]} failed`).trim());
+    };
+    return {
+        async initWithCommit(dir, message) {
+            await must(['init', '-b', 'main'], dir);
+            await must(['add', '-A'], dir);
+            await must([...identity, 'commit', '-m', message], dir);
+        },
+    };
+}
+/** Specs adapter: writes the project's own ticket store (the board reads it). */
+function createSampleSpecs(now = () => new Date()) {
+    return {
+        install(dir, sample, locale) {
+            const ids = [];
+            const stamp = now().toISOString();
+            (0, ticket_store_1.mutateStore)((0, ticket_store_1.resolveTicketStoragePath)(dir), (store) => {
+                for (const spec of sample.specs) {
+                    const text = spec.text[locale] ?? spec.text.en;
+                    const id = store.next_id++;
+                    const ticket = {
+                        id,
+                        title: text.title,
+                        description: text.description,
+                        status: 'todo',
+                        priority: spec.priority,
+                        labels: [...spec.labels],
+                        assignee: null,
+                        prerequisites: [],
+                        metadata: { effort_level: spec.effort, area: sample.id },
+                        comments: [],
+                        origin_conversation_id: null,
+                        is_epic: false,
+                        parent_epic_id: null,
+                        execution_order: null,
+                        short_summary: text.summary,
+                        created_at: stamp,
+                        updated_at: stamp,
+                        created_by: 'specrails',
+                        source: 'manual',
+                    };
+                    store.tickets[String(id)] = ticket;
+                    ids.push(id);
+                }
+            });
+            return ids;
+        },
+    };
+}
+/** App-wide record in desktop_settings (one sample at a time). */
+function createSampleState(settings) {
+    return {
+        read() {
+            const raw = settings.get(domain_1.SAMPLE_SETTING_KEY);
+            if (!raw)
+                return null;
+            try {
+                const value = JSON.parse(raw);
+                if (typeof value.projectId !== 'string' || typeof value.path !== 'string' || typeof value.sampleId !== 'string')
+                    return null;
+                return {
+                    sampleId: value.sampleId,
+                    projectId: value.projectId,
+                    path: value.path,
+                    specIds: Array.isArray(value.specIds) ? value.specIds.filter((id) => typeof id === 'number') : [],
+                    createdAt: typeof value.createdAt === 'string' ? value.createdAt : '',
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+        write: (record) => settings.set(domain_1.SAMPLE_SETTING_KEY, JSON.stringify(record)),
+        clear: () => settings.set(domain_1.SAMPLE_SETTING_KEY, ''),
+    };
+}

package/server/dist/modules/onboarding/application.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultSampleParent = defaultSampleParent;
+exports.currentSample = currentSample;
+exports.createSample = createSample;
+exports.removeSample = removeSample;
+const domain_1 = require("./domain");
+/** The default parent folder (`~/Specrails Samples`). */
+function defaultSampleParent(files) {
+    return files.join(files.homeDir(), domain_1.SAMPLE_PARENT_DIR_NAME);
+}
+/**
+ * The recorded sample, or null. A record whose project is no longer registered
+ * (removed by hand) is dropped, so the person can create a fresh one.
+ */
+function currentSample(deps) {
+    const record = deps.state.read();
+    if (!record)
+        return null;
+    const project = deps.projects.get(record.projectId);
+    if (!project) {
+        deps.state.clear();
+        return null;
+    }
+    return { record, project };
+}
+function insideHome(deps, candidate) {
+    const home = deps.files.resolve(deps.files.homeDir());
+    const resolved = deps.files.resolve(candidate);
+    if (!(0, domain_1.isStrictlyInside)(home, resolved, deps.files.sep)) {
+        throw new domain_1.SampleError('outside_home', 'The sample must live inside your home folder', 400);
+    }
+    return resolved;
+}
+/**
+ * Copy the sample into a new folder, make it a git repository with one commit,
+ * install its specs and register it as a project. Idempotent: a second call
+ * returns the existing sample untouched. Every failure after the folder exists
+ * removes what this call created.
+ */
+async function createSample(deps, input) {
+    const sample = deps.samples.find((s) => s.id === input.sampleId);
+    if (!sample)
+        throw new domain_1.SampleError('unknown_sample', `Unknown sample "${input.sampleId}"`, 404);
+    const existing = currentSample(deps);
+    if (existing)
+        return { project: existing.project, record: existing.record, reused: true };
+    let target;
+    if (input.targetPath) {
+        target = insideHome(deps, input.targetPath);
+        if (deps.files.exists(target))
+            throw new domain_1.SampleError('path_exists', 'That folder already exists', 409);
+    }
+    else {
+        const parent = insideHome(deps, input.parentDir ?? defaultSampleParent(deps.files));
+        const name = (0, domain_1.firstFreeName)(sample.name, (candidate) => deps.files.exists(deps.files.join(parent, candidate)));
+        if (name === null)
+            throw new domain_1.SampleError('no_free_name', 'Could not find a free folder name', 409);
+        target = deps.files.join(parent, name);
+    }
+    let registered = null;
+    const rollback = () => {
+        if (registered) {
+            try {
+                deps.projects.unregister(registered.id);
+            }
+            catch { /* best effort */ }
+        }
+        try {
+            deps.files.remove(target);
+        }
+        catch { /* best effort */ }
+    };
+    try {
+        try {
+            deps.files.writeTree(target, sample.files);
+        }
+        catch (err) {
+            throw new domain_1.SampleError('write_failed', `Could not write the sample: ${err.message}`, 500);
+        }
+        try {
+            await deps.git.initWithCommit(target, sample.commitMessage);
+        }
+        catch (err) {
+            throw new domain_1.SampleError('git_failed', `git could not create the sample repository: ${err.message}`, 500);
+        }
+        const specIds = deps.specs.install(target, sample, input.locale);
+        try {
+            registered = deps.projects.register({ path: target, name: sample.name });
+        }
+        catch (err) {
+            throw new domain_1.SampleError('register_failed', `Could not register the sample project: ${err.message}`, 500);
+        }
+        const record = {
+            sampleId: sample.id,
+            projectId: registered.id,
+            path: target,
+            specIds,
+            createdAt: (deps.now?.() ?? new Date()).toISOString(),
+        };
+        deps.state.write(record);
+        return { project: registered, record, reused: false };
+    }
+    catch (err) {
+        rollback();
+        throw err;
+    }
+}
+/**
+ * Unregister the sample project and, only when asked, delete its folder. The
+ * folder is deleted only when it is the exact path recorded at creation, still
+ * strictly inside the home directory and still a git repository, so a stale or
+ * tampered record can never point the deletion elsewhere.
+ */
+function removeSample(deps, opts) {
+    const record = deps.state.read();
+    if (!record)
+        throw new domain_1.SampleError('not_found', 'There is no sample project', 404);
+    let deleteTarget = null;
+    if (opts.deleteFolder && deps.files.exists(record.path)) {
+        const resolved = insideHome(deps, record.path);
+        if (!deps.files.isGitRepo(resolved))
+            throw new domain_1.SampleError('unsafe_delete', 'The sample folder is no longer a git repository; it was left in place', 409);
+        deleteTarget = resolved;
+    }
+    const removedProject = deps.projects.isRegistered(record.projectId);
+    if (removedProject)
+        deps.projects.unregister(record.projectId);
+    if (deleteTarget)
+        deps.files.remove(deleteTarget);
+    deps.state.clear();
+    return { removedProject, deletedFolder: deleteTarget !== null };
+}