crewly 1.20.128 → 1.20.129

package/dist/backend/backend/src/services/onboarding/onboarding-checklist.service.js

@@ -0,0 +1,365 @@
+/**
+ * Onboarding checklist — the first-run steps after the harness is ready
+ * (specs/onboarding-harness-login.md, Phase 3):
+ *
+ *   harness → first team (starter template or Blank) → first task → Cloud → Slack
+ *
+ * Every step's `done` is read from the real system, not from UI flags:
+ *
+ * - `harness`: the orchestrator's harness is recorded, installed and not
+ *   known to be logged out (the same rule as the web setup redirect);
+ * - `team`: at least one team exists, or the owner chose Blank;
+ * - `first_task`: the owner has sent at least one message on any surface
+ *   (chat-v2 `user` rows an agent did not write), or a first task was handed
+ *   to the orchestrator from setup;
+ * - `cloud`: this instance is connected to Crewly Cloud;
+ * - `slack`: Slack is connected (Cloud-installed app or self-hosted tokens).
+ *
+ * The only stored flags are the dashboard card's `dismissed`, the Blank
+ * choice and the first-task record (`onboarding-state.store.ts`).
+ *
+ * Shared by the REST routes (`/api/onboarding/*`, also reachable from the
+ * phone / portal over the relay) and `crewly onboard`.
+ *
+ * @module services/onboarding/onboarding-checklist.service
+ */
+import { ONBOARDING_CONSTANTS, HARNESS_CONSTANTS, CLOUD_CONSTANTS } from '../../constants.js';
+/** A request the checklist cannot fulfil. */
+export class OnboardingError extends Error {
+    code;
+    /**
+     * @param code - Machine-readable code (mapped to an HTTP status by the controller)
+     * @param message - Human-readable message
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OnboardingError';
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Lower-case slug of ASCII letters, digits and dashes.
+ *
+ * @param value - Any text
+ * @returns Slug (may be empty for non-ASCII text)
+ */
+export function toSessionSlug(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * The Crewly Cloud sign-in that works from any device: Google sign-in on
+ * Cloud, ending on the portal's token page (token + refresh token to paste).
+ *
+ * @returns Absolute URL
+ */
+export function buildTokenPageSignInUrl() {
+    const tokenPage = `${ONBOARDING_CONSTANTS.CLOUD.CONSOLE_URL}${ONBOARDING_CONSTANTS.CLOUD.CLI_TOKEN_PATH}`;
+    return `${CLOUD_CONSTANTS.DEFAULT_CLOUD_URL}${ONBOARDING_CONSTANTS.CLOUD.GOOGLE_START_PATH}?redirect=${encodeURIComponent(tokenPage)}`;
+}
+/**
+ * The message the orchestrator receives for a first task.
+ *
+ * @param text - The owner's words
+ * @param team - Team it is meant for, or null for the orchestrator itself
+ * @returns Message content
+ */
+export function buildFirstTaskMessage(text, team) {
+    const lines = [ONBOARDING_CONSTANTS.FIRST_TASK_HEADER];
+    if (team) {
+        lines.push(`请交给团队「${team.name}」(team id: ${team.id}) 来做；团队还没启动的话先启动它。`);
+    }
+    lines.push('', text.trim());
+    return lines.join('\n');
+}
+/**
+ * Starter DTO for a template.
+ *
+ * @param template - Template with onboarding metadata
+ * @param onboarding - Its onboarding metadata
+ * @returns Starter
+ */
+function templateToStarter(template, onboarding) {
+    return {
+        id: template.id,
+        name: template.name,
+        label: onboarding.label,
+        tagline: onboarding.tagline,
+        description: template.description,
+        recommended: onboarding.recommended,
+        members: template.roles.flatMap((role) => Array.from({ length: Math.max(1, role.count) }, (_, i) => ({
+            name: role.count > 1 ? `${role.defaultName}${i + 1}` : role.defaultName,
+            role: role.role,
+        }))),
+        suggestions: [...onboarding.suggestions],
+    };
+}
+/**
+ * Error text for a failed step read.
+ *
+ * @param error - Thrown value
+ * @returns Message
+ */
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+// =============================================================================
+// Service
+// =============================================================================
+/**
+ * First-run checklist: step states, starter teams, the first task, dismissal.
+ */
+export class OnboardingChecklistService {
+    deps;
+    /**
+     * @param deps - Dependencies
+     */
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Read every step from the live system.
+     *
+     * A step whose source fails reads as not done, with `detail.error` set;
+     * the rest of the checklist is still returned.
+     *
+     * @returns The checklist
+     */
+    async getChecklist() {
+        const state = await this.deps.store.read();
+        const steps = await Promise.all([
+            this.harnessStep(),
+            this.teamStep(state),
+            this.firstTaskStep(state),
+            this.cloudStep(),
+            this.slackStep(),
+        ]);
+        const doneCount = steps.filter((s) => s.done).length;
+        return {
+            steps,
+            doneCount,
+            total: steps.length,
+            allDone: doneCount === steps.length,
+            dismissed: state.dismissedAt !== null,
+            dismissedAt: state.dismissedAt,
+        };
+    }
+    /**
+     * The starter teams: templates marked `onboarding` (by `order`), then Blank.
+     *
+     * @returns Starters, recommended first
+     */
+    listStarters() {
+        const starters = this.deps
+            .templates()
+            .listOnboardingStarters()
+            .filter((t) => !!t.onboarding)
+            .map((t) => templateToStarter(t, t.onboarding));
+        const blank = ONBOARDING_CONSTANTS.BLANK_STARTER;
+        starters.push({
+            id: ONBOARDING_CONSTANTS.BLANK_STARTER_ID,
+            name: blank.NAME,
+            label: blank.LABEL,
+            tagline: blank.TAGLINE,
+            description: blank.TAGLINE,
+            recommended: false,
+            members: [],
+            suggestions: [...blank.SUGGESTIONS],
+        });
+        return starters;
+    }
+    /**
+     * Create the first team from a starter, or record the Blank choice.
+     *
+     * Idempotent: a team already created from the same template is returned
+     * (a double tap on a phone must not make two teams). Members run on the
+     * orchestrator's harness, the only one first-time setup installs.
+     *
+     * @param starterId - Template id of a starter, or `blank`
+     * @returns The team (null for Blank) and whether it was created now
+     * @throws OnboardingError `unknown_starter`
+     */
+    async createStarterTeam(starterId) {
+        if (starterId === ONBOARDING_CONSTANTS.BLANK_STARTER_ID) {
+            const now = this.deps.now().toISOString();
+            await this.deps.store.update((cur) => ({ blankChosenAt: cur.blankChosenAt ?? now }));
+            return { starterId, team: null, created: false };
+        }
+        const source = this.deps.templates();
+        const template = source.getTemplate(starterId);
+        if (!template || !template.onboarding) {
+            throw new OnboardingError('unknown_starter', `"${starterId}" is not a starter team`);
+        }
+        const existing = (await this.deps.listTeams()).find((t) => t.templateId === template.id);
+        if (existing)
+            return { starterId, team: existing, created: false };
+        const result = source.createTeamFromTemplate(template.id, template.name);
+        if (!result)
+            throw new OnboardingError('unknown_starter', `"${starterId}" is not a starter team`);
+        const runtime = (await this.deps.getOrcHarness()) ?? HARNESS_CONSTANTS.DEFAULT_ORC_HARNESS;
+        const teamSlug = toSessionSlug(template.id);
+        for (const member of result.team.members) {
+            member.runtimeType = runtime;
+            member.sessionName = `${teamSlug}-${toSessionSlug(member.name) || 'member'}-${member.id.slice(0, 8)}`;
+        }
+        await this.deps.saveTeam(result.team);
+        return { starterId, team: result.team, created: true };
+    }
+    /**
+     * Hand the owner's first task to the orchestrator (through the chat path,
+     * so it is a normal owner message: ticket intake, queue while offline).
+     *
+     * @param text - The owner's words
+     * @param teamId - Team it is meant for (omit for the orchestrator itself)
+     * @returns Delivery result
+     * @throws OnboardingError `invalid_task` | `unknown_team`
+     */
+    async sendFirstTask(text, teamId) {
+        if (typeof text !== 'string' || text.trim().length === 0) {
+            throw new OnboardingError('invalid_task', 'Write what the team should do first');
+        }
+        if (text.length > ONBOARDING_CONSTANTS.FIRST_TASK_MAX_LENGTH) {
+            throw new OnboardingError('invalid_task', `Keep the first task under ${ONBOARDING_CONSTANTS.FIRST_TASK_MAX_LENGTH} characters`);
+        }
+        let team = null;
+        if (teamId !== undefined && teamId !== null && teamId !== '') {
+            team = (await this.deps.listTeams()).find((t) => t.id === teamId) ?? null;
+            if (!team)
+                throw new OnboardingError('unknown_team', `Team "${String(teamId)}" not found`);
+        }
+        const sent = await this.deps.sendToOrchestrator(buildFirstTaskMessage(text, team), {
+            source: ONBOARDING_CONSTANTS.FIRST_TASK_SOURCE,
+            ...(team ? { teamId: team.id } : {}),
+        });
+        let sentAt = null;
+        if (sent.forwarded) {
+            sentAt = this.deps.now().toISOString();
+            const record = { sentAt, teamId: team?.id ?? null, conversationId: sent.conversationId };
+            await this.deps.store.update(() => ({ firstTask: record, pendingFirstTask: null }));
+        }
+        return {
+            forwarded: sent.forwarded,
+            queued: sent.queued,
+            conversationId: sent.conversationId,
+            teamId: team?.id ?? null,
+            sentAt,
+            message: sent.error,
+        };
+    }
+    /**
+     * Keep a first task typed while the backend was down (`crewly onboard`).
+     *
+     * @param text - The owner's words
+     * @param teamId - Team it is meant for, or null
+     * @throws OnboardingError `invalid_task`
+     */
+    async queuePendingFirstTask(text, teamId) {
+        if (text.trim().length === 0 || text.length > ONBOARDING_CONSTANTS.FIRST_TASK_MAX_LENGTH) {
+            throw new OnboardingError('invalid_task', 'Write what the team should do first');
+        }
+        const createdAt = this.deps.now().toISOString();
+        await this.deps.store.update(() => ({ pendingFirstTask: { text: text.trim(), teamId, createdAt } }));
+    }
+    /**
+     * Deliver a pending first task (called when the backend starts). A team
+     * that no longer exists sends it to the orchestrator itself.
+     *
+     * @returns The delivery result, or null when nothing was pending
+     */
+    async deliverPendingFirstTask() {
+        const { pendingFirstTask } = await this.deps.store.read();
+        if (!pendingFirstTask)
+            return null;
+        const teams = await this.deps.listTeams();
+        const teamId = pendingFirstTask.teamId && teams.some((t) => t.id === pendingFirstTask.teamId) ? pendingFirstTask.teamId : undefined;
+        return this.sendFirstTask(pendingFirstTask.text, teamId);
+    }
+    /**
+     * Hide or show the dashboard checklist card.
+     *
+     * @param dismissed - True to hide
+     * @returns The checklist after the change
+     */
+    async setDismissed(dismissed) {
+        const now = this.deps.now().toISOString();
+        await this.deps.store.update((cur) => ({ dismissedAt: dismissed ? cur.dismissedAt ?? now : null }));
+        return this.getChecklist();
+    }
+    // ---------------------------------------------------------------------------
+    // Steps
+    // ---------------------------------------------------------------------------
+    /** @returns Harness step */
+    async harnessStep() {
+        try {
+            const detail = await this.deps.getHarnessState();
+            const done = detail.orcHarness !== null && detail.installed && detail.loginState !== 'logged_out';
+            return { id: 'harness', done, detail };
+        }
+        catch (error) {
+            return { id: 'harness', done: false, detail: { orcHarness: null, installed: false, loginState: null, error: errorText(error) } };
+        }
+    }
+    /**
+     * @param state - Stored onboarding state
+     * @returns Team step
+     */
+    async teamStep(state) {
+        const blank = state.blankChosenAt !== null;
+        try {
+            const teams = (await this.deps.listTeams()).map((t) => ({ id: t.id, name: t.name, templateId: t.templateId ?? null }));
+            return { id: 'team', done: teams.length > 0 || blank, detail: { teams, blank } };
+        }
+        catch (error) {
+            return { id: 'team', done: blank, detail: { teams: [], blank, error: errorText(error) } };
+        }
+    }
+    /**
+     * @param state - Stored onboarding state
+     * @returns First-task step
+     */
+    async firstTaskStep(state) {
+        const sentAt = state.firstTask?.sentAt ?? null;
+        const pending = state.pendingFirstTask !== null;
+        try {
+            const ownerMessageSeen = this.deps.hasOwnerMessage();
+            return { id: 'first_task', done: sentAt !== null || ownerMessageSeen, detail: { sentAt, ownerMessageSeen, pending } };
+        }
+        catch (error) {
+            return { id: 'first_task', done: sentAt !== null, detail: { sentAt, ownerMessageSeen: false, pending, error: errorText(error) } };
+        }
+    }
+    /** @returns Cloud step */
+    async cloudStep() {
+        const tokenPageSignInUrl = buildTokenPageSignInUrl();
+        try {
+            const { connected, tier } = this.deps.getCloudState();
+            return { id: 'cloud', done: connected, detail: { connected, tier: connected ? tier : null, tokenPageSignInUrl } };
+        }
+        catch (error) {
+            return { id: 'cloud', done: false, detail: { connected: false, tier: null, tokenPageSignInUrl, error: errorText(error) } };
+        }
+    }
+    /** @returns Slack step */
+    async slackStep() {
+        let cloudConnected = false;
+        try {
+            cloudConnected = this.deps.getCloudState().connected;
+        }
+        catch {
+            // Reported by the Cloud step.
+        }
+        try {
+            const connected = this.deps.isSlackConnected();
+            return { id: 'slack', done: connected, detail: { connected, cloudConnected } };
+        }
+        catch (error) {
+            return { id: 'slack', done: false, detail: { connected: false, cloudConnected, error: errorText(error) } };
+        }
+    }
+}
+//# sourceMappingURL=onboarding-checklist.service.js.map

package/dist/backend/backend/src/services/onboarding/onboarding-checklist.service.js.map

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

package/dist/backend/backend/src/services/onboarding/onboarding-state.store.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Onboarding state store — `<crewlyHome>/onboarding.json`.
+ *
+ * Holds the few things the first-run checklist cannot read from the rest of
+ * the system (specs/onboarding-harness-login.md, Phase 3):
+ *
+ * - `dismissedAt`: the owner hid the dashboard checklist card;
+ * - `blankChosenAt`: the owner chose "Blank" (the orchestrator only), which
+ *   completes the team step without a team;
+ * - `firstTask`: a first task that was handed to the orchestrator;
+ * - `pendingFirstTask`: a first task typed in `crewly onboard` while the
+ *   backend was down, delivered when the backend starts.
+ *
+ * Everything else (harness login, teams, Cloud, Slack) is read live.
+ * Writes are atomic (temp file + rename) and serialized per store.
+ *
+ * @module services/onboarding/onboarding-state.store
+ */
+/** A first task handed to the orchestrator. */
+export interface SentFirstTask {
+    /** ISO time it was handed over */
+    sentAt: string;
+    /** Team it was meant for (null = the orchestrator itself) */
+    teamId: string | null;
+    /** Chat conversation it was recorded in */
+    conversationId: string | null;
+}
+/** A first task waiting for the backend to start. */
+export interface PendingFirstTask {
+    /** The owner's words */
+    text: string;
+    /** Team it is meant for (null = the orchestrator itself) */
+    teamId: string | null;
+    /** ISO time it was typed */
+    createdAt: string;
+}
+/** Contents of `onboarding.json`. */
+export interface OnboardingState {
+    dismissedAt: string | null;
+    blankChosenAt: string | null;
+    firstTask: SentFirstTask | null;
+    pendingFirstTask: PendingFirstTask | null;
+}
+/** State of a machine that never saw onboarding. */
+export declare const EMPTY_ONBOARDING_STATE: OnboardingState;
+/**
+ * Normalize parsed JSON into a complete state (unknown / malformed fields are dropped).
+ *
+ * @param raw - Parsed file contents
+ * @returns A complete state
+ */
+export declare function normalizeOnboardingState(raw: unknown): OnboardingState;
+/**
+ * File-backed onboarding state.
+ */
+export declare class OnboardingStateStore {
+    private readonly filePath;
+    /** Serializes read-modify-write cycles */
+    private chain;
+    /**
+     * @param crewlyHome - Crewly home dir (defaults to `CREWLY_HOME` / `~/.crewly`)
+     */
+    constructor(crewlyHome?: string);
+    /**
+     * Path of the state file.
+     *
+     * @returns Absolute path
+     */
+    getFilePath(): string;
+    /**
+     * Read the state. A missing or unreadable file reads as empty.
+     *
+     * @returns The state
+     */
+    read(): Promise<OnboardingState>;
+    /**
+     * Apply a change and write the result atomically.
+     *
+     * @param change - Returns the fields to change
+     * @returns The state after the change
+     *
+     * @example
+     * ```ts
+     * await store.update(() => ({ dismissedAt: new Date().toISOString() }));
+     * ```
+     */
+    update(change: (current: OnboardingState) => Partial<OnboardingState>): Promise<OnboardingState>;
+}
+//# sourceMappingURL=onboarding-state.store.d.ts.map

package/dist/backend/backend/src/services/onboarding/onboarding-state.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-state.store.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/onboarding/onboarding-state.store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC7B,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAChC,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,aAAa,GAAG,IAAI,CAAC;IAChC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC1C;AAED,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,EAAE,eAKnC,CAAC;AAYH;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,CAiBtE;AAED;;GAEG;AACH,qBAAa,oBAAoB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,0CAA0C;IAC1C,OAAO,CAAC,KAAK,CAAuC;IAEpD;;OAEG;gBACS,UAAU,GAAE,MAA4B;IAIpD;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC;IAQtC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;CAchG"}

package/dist/backend/backend/src/services/onboarding/onboarding-state.store.js

@@ -0,0 +1,122 @@
+/**
+ * Onboarding state store — `<crewlyHome>/onboarding.json`.
+ *
+ * Holds the few things the first-run checklist cannot read from the rest of
+ * the system (specs/onboarding-harness-login.md, Phase 3):
+ *
+ * - `dismissedAt`: the owner hid the dashboard checklist card;
+ * - `blankChosenAt`: the owner chose "Blank" (the orchestrator only), which
+ *   completes the team step without a team;
+ * - `firstTask`: a first task that was handed to the orchestrator;
+ * - `pendingFirstTask`: a first task typed in `crewly onboard` while the
+ *   backend was down, delivered when the backend starts.
+ *
+ * Everything else (harness login, teams, Cloud, Slack) is read live.
+ * Writes are atomic (temp file + rename) and serialized per store.
+ *
+ * @module services/onboarding/onboarding-state.store
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import { ONBOARDING_CONSTANTS } from '../../constants.js';
+import { getCrewlyHomePath } from '../core/crewly-home.utils.js';
+/** State of a machine that never saw onboarding. */
+export const EMPTY_ONBOARDING_STATE = Object.freeze({
+    dismissedAt: null,
+    blankChosenAt: null,
+    firstTask: null,
+    pendingFirstTask: null,
+});
+/**
+ * Read an ISO string field, or null.
+ *
+ * @param value - Candidate
+ * @returns The string, or null
+ */
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/**
+ * Normalize parsed JSON into a complete state (unknown / malformed fields are dropped).
+ *
+ * @param raw - Parsed file contents
+ * @returns A complete state
+ */
+export function normalizeOnboardingState(raw) {
+    if (!raw || typeof raw !== 'object')
+        return { ...EMPTY_ONBOARDING_STATE };
+    const o = raw;
+    const task = o.firstTask;
+    const pending = o.pendingFirstTask;
+    return {
+        dismissedAt: asString(o.dismissedAt),
+        blankChosenAt: asString(o.blankChosenAt),
+        firstTask: task && typeof task === 'object' && asString(task.sentAt)
+            ? { sentAt: task.sentAt, teamId: asString(task.teamId), conversationId: asString(task.conversationId) }
+            : null,
+        pendingFirstTask: pending && typeof pending === 'object' && asString(pending.text) && asString(pending.createdAt)
+            ? { text: pending.text, teamId: asString(pending.teamId), createdAt: pending.createdAt }
+            : null,
+    };
+}
+/**
+ * File-backed onboarding state.
+ */
+export class OnboardingStateStore {
+    filePath;
+    /** Serializes read-modify-write cycles */
+    chain = Promise.resolve();
+    /**
+     * @param crewlyHome - Crewly home dir (defaults to `CREWLY_HOME` / `~/.crewly`)
+     */
+    constructor(crewlyHome = getCrewlyHomePath()) {
+        this.filePath = path.join(crewlyHome, ONBOARDING_CONSTANTS.STATE_FILE);
+    }
+    /**
+     * Path of the state file.
+     *
+     * @returns Absolute path
+     */
+    getFilePath() {
+        return this.filePath;
+    }
+    /**
+     * Read the state. A missing or unreadable file reads as empty.
+     *
+     * @returns The state
+     */
+    async read() {
+        try {
+            return normalizeOnboardingState(JSON.parse(await fs.readFile(this.filePath, 'utf-8')));
+        }
+        catch {
+            return { ...EMPTY_ONBOARDING_STATE };
+        }
+    }
+    /**
+     * Apply a change and write the result atomically.
+     *
+     * @param change - Returns the fields to change
+     * @returns The state after the change
+     *
+     * @example
+     * ```ts
+     * await store.update(() => ({ dismissedAt: new Date().toISOString() }));
+     * ```
+     */
+    update(change) {
+        const run = async () => {
+            const current = await this.read();
+            const next = { ...current, ...change(current) };
+            await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+            const tmp = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+            await fs.writeFile(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf-8');
+            await fs.rename(tmp, this.filePath);
+            return next;
+        };
+        const result = this.chain.then(run, run);
+        this.chain = result.catch(() => undefined);
+        return result;
+    }
+}
+//# sourceMappingURL=onboarding-state.store.js.map

package/dist/backend/backend/src/services/onboarding/onboarding-state.store.js.map

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

package/dist/backend/backend/src/services/template/template.service.d.ts

@@ -7,7 +7,7 @@
  *
  * @module services/template/template
  */
-import type { TeamTemplate } from '../../types/team-template.types.js';
+import type { TeamTemplate, TemplateOnboarding } from '../../types/team-template.types.js';
 import type { Team } from '../../types/index.js';
 import { type CloudTier } from '../../constants.js';
 /** Result of creating a team from a template */
@@ -36,6 +36,8 @@ export interface TemplateSummary {
     source: TemplateSource;
     /** Minimum tier required to use this template */
     requiredTier?: CloudTier;
+    /** First-run starter metadata (only on onboarding starters) */
+    onboarding?: TemplateOnboarding;
 }
 /**
  * TemplateService manages team templates.
@@ -78,6 +80,18 @@ export declare class TemplateService {
      * @returns Array of local template summaries
      */
     listTemplates(): TemplateSummary[];
+    /**
+     * The first-run starter templates (those with `onboarding` metadata),
+     * ordered by `onboarding.order`.
+     *
+     * @returns Starter templates, first-shown first
+     *
+     * @example
+     * ```ts
+     * const [recommended] = TemplateService.getInstance().listOnboardingStarters();
+     * ```
+     */
+    listOnboardingStarters(): TeamTemplate[];
     /**
      * Get a specific template by ID.
      *

package/dist/backend/backend/src/services/template/template.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/template/template.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,oCAAoC,CAAC;AAErF,OAAO,KAAK,EAAc,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AA8BrE,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,uBAAuB;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,iDAAiD;IACjD,YAAY,CAAC,EAAE,SAAS,CAAC;CAC1B;AAMD;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgC;IAEvD,qCAAqC;IACrC,OAAO,CAAC,SAAS,CAAwC;IAEzD,+BAA+B;IAC/B,OAAO,CAAC,YAAY,CAAS;IAE7B,yCAAyC;IACzC,OAAO,CAAC,MAAM,CAAkB;IAEhC,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe;IAO1D;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;;OAMG;IACH,aAAa,IAAI,MAAM;IA8BvB;;;;OAIG;IACH,aAAa,IAAI,eAAe,EAAE;IAmBlC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAK5C;;;;;;;;;OASG;IACH,sBAAsB,CACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE,SAAS,GACnB,wBAAwB,GAAG,IAAI;IAyIlC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAiDrB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;IAQ1B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;CAuG3B"}
+{"version":3,"file":"template.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/template/template.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAgB,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAEzG,OAAO,KAAK,EAAc,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAAE,KAAK,SAAS,EAAmB,MAAM,oBAAoB,CAAC;AA8BrE,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,uBAAuB;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,mCAAmC;AACnC,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC;AAErC,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,MAAM,EAAE,cAAc,CAAC;IACvB,iDAAiD;IACjD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAMD;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAgC;IAEvD,qCAAqC;IACrC,OAAO,CAAC,SAAS,CAAwC;IAEzD,+BAA+B;IAC/B,OAAO,CAAC,YAAY,CAAS;IAE7B,yCAAyC;IACzC,OAAO,CAAC,MAAM,CAAkB;IAEhC,OAAO;IAIP;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,eAAe;IAO1D;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,IAAI;IAI5B;;;;;;OAMG;IACH,aAAa,IAAI,MAAM;IA8BvB;;;;OAIG;IACH,aAAa,IAAI,eAAe,EAAE;IAmBlC;;;;;;;;;;OAUG;IACH,sBAAsB,IAAI,YAAY,EAAE;IAQxC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAK5C;;;;;;;;;OASG;IACH,sBAAsB,CACpB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,QAAQ,CAAC,EAAE,SAAS,GACnB,wBAAwB,GAAG,IAAI;IAyIlC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAiDrB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;IAQ1B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;CAyG3B"}