@playcraft/cli 0.1.70 → 0.1.72

package/dist/project-skills/remote-commands.js

@@ -0,0 +1,87 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { remoteSkillMatchResultSchema } from '@playcraft/common/project-skills';
+import { RemoteSkillClient } from './remote-client.js';
+import { prepareRemoteSkillSelection } from './remote-prepare.js';
+import { findManagedSkillsRoot, normalizeSkillEngine } from './search.js';
+import { printSkillSearchError } from './search-command.js';
+import { projectSkillsMessage as t } from './messages.js';
+export async function matchRemoteSkills(options) {
+    const limit = Number(options.limit ?? 20);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error(t('searchInvalidLimit'));
+    const engine = options.engine ? normalizeSkillEngine(options.engine) : undefined;
+    if (engine !== undefined && engine !== 'phaser' && engine !== 'threejs')
+        throw new Error(t('remoteInvalidEngine'));
+    const result = await new RemoteSkillClient({ cwd: resolve(options.dir), url: options.url }).match({ query: options.intent, engine, limit });
+    if (options.json)
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else {
+        console.log(t('remoteSource'));
+        console.log(result.total ? `${t('searchSummary')} ${result.total}` : t('remoteNoMatches'));
+        for (const skill of result.items) {
+            console.log(`  ${skill.skillRef}@${skill.version}  ${skill.name}`);
+            if (skill.description)
+                console.log(`    ${skill.description}`);
+            if (skill.matchedTerms.length)
+                console.log(`    ${skill.matchedTerms.join(', ')}`);
+        }
+        console.log(t('remotePrepareHint'));
+    }
+    return result;
+}
+async function readMatchReceipt(path) {
+    const file = await open(resolve(path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 4 * 1024 * 1024)
+            throw new Error(t('remoteInvalidMatchFile'));
+        return remoteSkillMatchResultSchema.parse(JSON.parse(await file.readFile('utf8')));
+    }
+    finally {
+        await file.close();
+    }
+}
+export function registerRemoteSkillPrepareCommand(skills) {
+    skills.command('prepare').description(t('remotePrepare'))
+        .requiredOption('--from-match <path>', t('remoteMatchFile'))
+        .requiredOption('--skills <refs>', t('remoteSelectedRefs'))
+        .option('--dir <path>', t('directory'), '.')
+        .option('--url <url>', t('remoteUrl'))
+        .option('--prepare-only', t('remotePrepareOnly'))
+        .option('--json', t('json'))
+        .action(async (options) => {
+        try {
+            const match = await readMatchReceipt(options.fromMatch);
+            const refs = [...new Set(options.skills.split(',').map(ref => ref.trim()).filter(Boolean))];
+            if (!refs.length || refs.length > 50)
+                throw new Error(t('remoteInvalidSelection'));
+            const selected = refs.map(ref => {
+                const candidates = match.items.filter(skill => skill.skillRef === ref || `${skill.skillRef}@${skill.version}` === ref);
+                if (candidates.length !== 1)
+                    throw new Error(`${t('remoteInvalidSelection')}: ${ref}`);
+                const skill = candidates[0];
+                return { skillRef: skill.skillRef, skillVersionId: skill.skillVersionId, version: skill.version, artifactHash: skill.artifactHash };
+            });
+            const engine = match.engine === 'phaser' || match.engine === 'threejs' ? match.engine : undefined;
+            const client = new RemoteSkillClient({ cwd: resolve(options.dir), url: options.url });
+            const selection = await client.select({ skills: selected, engine, catalogHash: match.catalogHash });
+            const root = client.hasExecutionBridge() ? await findManagedSkillsRoot(options.dir) ?? resolve(options.dir) : resolve(options.dir);
+            const prepared = await prepareRemoteSkillSelection(root, selection, entry => client.artifact(selection, entry));
+            const activation = options.prepareOnly ? undefined : await client.activate(selection.selectionId);
+            const result = activation ? { ...prepared, status: activation.status, activation } : prepared;
+            if (options.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            else {
+                console.log(t('remotePrepared'));
+                console.log(result.directory);
+                console.log(t(activation?.status === 'activation_requested' ? 'remoteActivationRequested'
+                    : activation?.status === 'already_active' ? 'remoteAlreadyActive' : 'remoteActivationRequired'));
+            }
+        }
+        catch (error) {
+            printSkillSearchError(error, options.json);
+        }
+    });
+}

package/dist/project-skills/remote-prepare.js

@@ -0,0 +1,223 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { canonicalProjectSkillsJson, parseRemoteSkillSelectionResult, projectSkillsDigest, } from '@playcraft/common/project-skills';
+import { ensureProjectSkillDirectory, readLockedProjectSkillCatalog } from './discovery.js';
+import { excludeFromGit } from '../workspace-runtime/workspaces/dependencies.js';
+const MAX_RECEIPT_BYTES = 16 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
+const receiptName = 'selection.json';
+const PROCESS_STARTED_AT = Math.round(Date.now() - process.uptime() * 1000);
+async function readPreparationLease(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw error;
+        throw new Error('remote_skill_selection_lease_invalid');
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 2048)
+            throw new Error('remote_skill_selection_lease_invalid');
+        const bytes = await handle.readFile();
+        let record;
+        try {
+            record = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            throw new Error('remote_skill_selection_lease_invalid');
+        }
+        if (!record || record.version !== 1 || !/^[a-f0-9]{64}$/.test(record.selectionId)
+            || !Number.isSafeInteger(record.pid) || record.pid < 1 || record.pid > 2_147_483_647
+            || !Number.isSafeInteger(record.processStartedAt) || record.processStartedAt < 1
+            || typeof record.nonce !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(record.nonce))
+            throw new Error('remote_skill_selection_lease_invalid');
+        return { bytes, ino: stat.ino, dev: stat.dev, record };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function preparationOwnerExited(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+const samePreparationLease = (left, right) => left.ino === right.ino && left.dev === right.dev && left.bytes.equals(right.bytes);
+async function ownsPreparationLease(path, expected) {
+    try {
+        return samePreparationLease(await readPreparationLease(path), expected);
+    }
+    catch {
+        return false;
+    }
+}
+async function retirePreparationLease(path, expected, mayRemove = () => true) {
+    if (!await ownsPreparationLease(path, expected))
+        return false;
+    const retired = `${path}.${randomUUID()}.retired`;
+    try {
+        await rename(path, retired);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (await ownsPreparationLease(retired, expected) && mayRemove()) {
+        await rm(retired);
+        return true;
+    }
+    // Exclusive restoration never overwrites a concurrently created lease. If another
+    // owner claimed the original path, retain these unknown bytes under the retired name.
+    try {
+        await link(retired, path);
+        await rm(retired);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return false;
+}
+async function acquirePreparationLease(path, selectionId) {
+    const create = async () => {
+        const handle = await open(path, 'wx', 0o600);
+        const record = { version: 1, selectionId, pid: process.pid,
+            processStartedAt: PROCESS_STARTED_AT, nonce: randomUUID() };
+        const bytes = Buffer.from(JSON.stringify(record));
+        try {
+            await handle.writeFile(bytes);
+            const stat = await handle.stat();
+            return { handle, bytes, record, ino: stat.ino, dev: stat.dev };
+        }
+        catch (error) {
+            await handle.close();
+            // A partially written lease has no proof of ownership and remains fail-closed.
+            throw error;
+        }
+    };
+    try {
+        return await create();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const previous = await readPreparationLease(path);
+    if (previous.record.selectionId !== selectionId)
+        throw new Error('remote_skill_selection_lease_invalid');
+    if (!preparationOwnerExited(previous.record.pid))
+        throw new Error('remote_skill_selection_busy');
+    if (!await retirePreparationLease(path, previous, () => preparationOwnerExited(previous.record.pid)))
+        throw new Error('remote_skill_selection_lease_changed');
+    try {
+        return await create();
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error('remote_skill_selection_busy');
+        throw error;
+    }
+}
+async function exists(path) {
+    return lstat(path).then(stat => stat, (error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+}
+function identity(selection) {
+    return projectSkillsDigest({ declaration: selection.declaration, lock: selection.lock,
+        skills: selection.skills.map(({ skillRef, skillVersionId, version, artifactHash }) => ({ skillRef, skillVersionId, version, artifactHash })).sort((a, b) => a.skillRef.localeCompare(b.skillRef)) });
+}
+async function readReceipt(directory) {
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('remote_skill_selection_path_invalid');
+    const receipt = join(directory, receiptName);
+    const file = await lstat(receipt);
+    if (!file.isFile() || file.isSymbolicLink() || file.nlink !== 1 || file.size > MAX_RECEIPT_BYTES)
+        throw new Error('remote_skill_selection_path_invalid');
+    return parseRemoteSkillSelectionResult(JSON.parse(await readFile(receipt, 'utf8')));
+}
+async function prepared(directory, selection) {
+    const saved = await readReceipt(directory);
+    if (identity(saved) !== identity(selection))
+        throw new Error('remote_skill_selection_conflict');
+    const catalog = await readLockedProjectSkillCatalog(directory, join(directory, '.playcraft/skill-artifacts'));
+    if (catalog.lockHash !== selection.lockHash || catalog.skills.length !== selection.lock.entries.length)
+        throw new Error('remote_skill_selection_conflict');
+    return { status: 'prepared_requires_activation', executionReady: false,
+        selectionId: selection.selectionId, lockHash: selection.lockHash, directory,
+        skills: catalog.skills.map(({ entryKey, skillRef, revision, artifactHash, name, description, skillDir, path }) => ({ entryKey, skillRef, revision, artifactHash, name, description, skillDir, path })) };
+}
+/** Downloads a separate exact selection; never changes the project's active declaration or lock. */
+export async function prepareRemoteSkillSelection(directory, input, loadArtifact) {
+    const selection = parseRemoteSkillSelectionResult(input);
+    if (!selection.lock.entries.length || selection.declaration.entries.some(entry => entry.source.kind !== 'registry' || !entry.enabled || entry.surface !== 'sandbox-agent'))
+        throw new Error('invalid_remote_skill_selection');
+    const selectedBytes = canonicalProjectSkillsJson(selection);
+    if (Buffer.byteLength(selectedBytes) > MAX_RECEIPT_BYTES)
+        throw new Error('remote_skill_selection_too_large');
+    const suppliedRoot = resolve(directory);
+    const stat = await lstat(suppliedRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('remote_skill_selection_path_invalid');
+    const root = await realpath(suppliedRoot);
+    await excludeFromGit(root, '/.playcraft/skill-selections/');
+    const parent = await ensureProjectSkillDirectory(root, '.playcraft/skill-selections', true);
+    const target = join(parent, selection.selectionId);
+    if (await exists(target))
+        return prepared(target, selection);
+    const leasePath = join(parent, `.${selection.selectionId}.prepare.lock`);
+    const lease = await acquirePreparationLease(leasePath, selection.selectionId);
+    const stageName = `.${selection.selectionId}.${randomUUID()}.tmp`;
+    const stage = join(parent, stageName);
+    let published = false;
+    try {
+        if (await exists(target))
+            return prepared(target, selection);
+        await ensureProjectSkillDirectory(parent, stageName);
+        const management = await ensureProjectSkillDirectory(stage, '.playcraft/skill-artifacts');
+        const snapshots = [
+            ['skills.json', selection.declaration], ['skills.lock.json', selection.lock],
+        ];
+        for (const [name, value] of snapshots) {
+            const bytes = canonicalProjectSkillsJson(value);
+            if (Buffer.byteLength(bytes) > 1024 * 1024)
+                throw new Error('remote_skill_selection_too_large');
+            await writeFile(join(stage, '.playcraft', name), bytes, { flag: 'wx', mode: 0o644 });
+        }
+        await readLockedProjectSkillCatalog(stage, management, async (entry) => {
+            const archive = await loadArtifact(entry);
+            if (!Buffer.isBuffer(archive) || archive.byteLength > MAX_ARTIFACT_BYTES
+                || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+                throw new Error('remote_skill_artifact_digest_mismatch');
+            return archive;
+        });
+        await writeFile(join(stage, receiptName), selectedBytes, { flag: 'wx', mode: 0o644 });
+        // Nothing under the deterministic selection name is visible until every bundle is verified.
+        if (!await ownsPreparationLease(leasePath, lease))
+            throw new Error('remote_skill_selection_lease_changed');
+        if (await exists(target))
+            throw new Error('remote_skill_selection_conflict');
+        await rename(stage, target);
+        published = true;
+        return await prepared(target, selection);
+    }
+    finally {
+        if (!published)
+            await rm(stage, { recursive: true, force: true });
+        await lease.handle.close();
+        await retirePreparationLease(leasePath, lease);
+    }
+}

package/dist/project-skills/search-command.js

@@ -0,0 +1,47 @@
+import { resolve } from 'node:path';
+import { projectSkillsMessage as t } from './messages.js';
+import { searchProjectSkills } from './search.js';
+export function printLockedSkillSearch(skills, total) {
+    console.log(t('searchLockedSource'));
+    console.log(total ? `${t('searchSummary')} ${total}` : t('searchNoMatches'));
+    for (const skill of skills) {
+        console.log(`  ${skill.skillRef}@${skill.revision}  ${skill.name}`);
+        if (skill.description)
+            console.log(`    ${skill.description}`);
+        console.log(`    ${skill.path}`);
+    }
+    if (skills.length)
+        console.log(t('searchReadPath'));
+}
+export function printSkillSearchError(error, json) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : 'skill_search_failed';
+    if (json)
+        process.stdout.write(`${JSON.stringify({ error: { code, message } })}\n`);
+    else
+        console.error(`${t('searchFailed')}: ${message}`);
+    process.exitCode = 1;
+}
+export function registerSkillSearchCommand(skills) {
+    skills.command('search').description(t('search'))
+        .option('--query <text>', t('searchQuery'), '')
+        .option('--engine <name>', t('searchEngine'))
+        .option('--dir <path>', t('directory'), '.')
+        .option('--limit <count>', t('searchLimit'), '20')
+        .option('--json', t('json'))
+        .action(async (options) => {
+        try {
+            const limit = Number(options.limit);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                throw new Error(t('searchInvalidLimit'));
+            const result = await searchProjectSkills(resolve(options.dir), { ...options, limit });
+            if (options.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            else
+                printLockedSkillSearch(result.skills, result.total);
+        }
+        catch (error) {
+            printSkillSearchError(error, options.json);
+        }
+    });
+}

package/dist/project-skills/search.js

@@ -0,0 +1,96 @@
+import { lstat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { readLockedProjectSkillCatalog } from './discovery.js';
+import { projectSkillsMessage as t } from './messages.js';
+/** A partial configuration is still managed and must fail validation, never fall through to scanning. */
+export async function findManagedSkillsRoot(directory) {
+    let root = resolve(directory);
+    const exists = async (file) => lstat(file).then(() => true, (error) => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+    while (true) {
+        if (await exists(join(root, '.playcraft/skills.json')) || await exists(join(root, '.playcraft/skills.lock.json')))
+            return root;
+        if (await exists(join(root, '.git')) || dirname(root) === root)
+            return null;
+        root = dirname(root);
+    }
+}
+const normalize = (value) => value.normalize('NFKC').toLowerCase();
+export const normalizeSkillEngine = (value) => normalize(value).replace(/[.\s-]/g, '');
+export function skillSearchTerms(query) {
+    const terms = new Set(normalize(query).split(/[\s,，、;；]+/u).filter(Boolean));
+    // Include words within natural-language Chinese queries and compound English tags.
+    const segmenter = new Intl.Segmenter('zh', { granularity: 'word' });
+    for (const { segment, isWordLike } of segmenter.segment(normalize(query))) {
+        if (isWordLike && segment.length > 1)
+            terms.add(segment);
+    }
+    return [...terms];
+}
+export function filterLockedSkillsByEngine(skills, target) {
+    if (!target)
+        return skills;
+    const engine = normalizeSkillEngine(target);
+    const byAtom = new Map(skills.filter(skill => skill.manifest).map(skill => [skill.manifest.atomId, skill]));
+    const rootEngine = (id) => /^(phaser|threejs)(?:\.aicomponent|-runtime)?$/.exec(id)?.[1];
+    const compatible = (skill, visited = new Set()) => {
+        if (visited.has(skill.entryKey))
+            return true;
+        visited.add(skill.entryKey);
+        const manifest = skill.manifest;
+        if (!manifest)
+            return true;
+        const ownEngine = rootEngine(manifest.atomId);
+        if (ownEngine && ownEngine !== engine)
+            return false;
+        const metadata = manifest;
+        const engines = [...(metadata.renderBackend ?? []), ...Object.keys(metadata.engineVariants ?? {})].map(normalize);
+        if (engines.length && !engines.includes(engine))
+            return false;
+        const pins = metadata.engineVariants?.[engine]?.imports ?? (manifest.imports ?? [])
+            .filter(item => item.edgeKind === 'requires' || item.slot === 'engine' || item.bindAs === 'engine')
+            .flatMap(item => item.pinAtomId ? [item.pinAtomId] : []);
+        return pins.every(id => {
+            const requiredEngine = rootEngine(id);
+            if (requiredEngine && requiredEngine !== engine)
+                return false;
+            const dependency = byAtom.get(id);
+            return !dependency || compatible(dependency, visited);
+        });
+    };
+    return skills.filter(skill => compatible(skill));
+}
+export function rankLockedProjectSkills(skills, options = {}) {
+    const terms = skillSearchTerms(options.query ?? '');
+    const ranked = filterLockedSkillsByEngine(skills, options.engine).flatMap((skill) => {
+        const manifest = skill.manifest;
+        const fields = [
+            [skill.name, 5], [skill.skillRef, 5],
+            [skill.triggers.join(' '), 4], [skill.tags.join(' '), 4], [skill.keywords.join(' '), 3],
+            [manifest?.label?.zh ?? '', 4], [manifest?.label?.en ?? '', 4], [skill.description, 1],
+        ];
+        let score = 0;
+        const matchedTerms = terms.filter(term => {
+            const weight = Math.max(0, ...fields.map(([value, boost]) => normalize(value).includes(term) ? boost : 0));
+            score += weight;
+            return weight > 0;
+        });
+        if (terms.length && !matchedTerms.length)
+            return [];
+        const { manifest: _manifest, ...metadata } = skill;
+        return [{ ...metadata, atomId: manifest?.atomId, score, matchedTerms }];
+    }).sort((a, b) => b.score - a.score || a.skillRef.localeCompare(b.skillRef));
+    return { total: ranked.length, skills: ranked.slice(0, options.limit ?? 20) };
+}
+export async function searchProjectSkills(directory, options = {}) {
+    const root = await findManagedSkillsRoot(directory);
+    if (!root)
+        throw new Error(t('searchRequiresLock'));
+    const catalog = await readLockedProjectSkillCatalog(root);
+    return { source: 'project-lock', lockHash: catalog.lockHash,
+        query: options.query ?? '', engine: options.engine ?? null,
+        ...rankLockedProjectSkills(catalog.skills, options) };
+}

package/dist/recording/project-digest.js

@@ -7,7 +7,7 @@ import { RecordingError } from './messages.js';
 const execute = promisify(execFile);
 const excludedNames = new Set(['.git', 'node_modules', '.DS_Store']);
 const excludedRoots = new Set(['.agents', '.claude', '.codex', '.next', '.vite', '.cache', '.tmp', 'tmp', 'temp', 'dist', 'build', 'coverage', '.playcraft-preview-out', '.playcraft-temp']);
-const excludedInternalPaths = ['.playcraft/video-replication', '.playcraft/skills', '.playcraft/skill-artifacts', '.playcraft/skills.json', '.playcraft/skills.lock.json', '.playcraft/workspace-context.json'];
+const excludedInternalPaths = ['.playcraft/video-replication', '.playcraft/skills', '.playcraft/skill-artifacts', '.playcraft/skill-selections', '.playcraft/skills.json', '.playcraft/skills.lock.json', '.playcraft/workspace-context.json'];
 const inside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
 const canonicalPath = async (path) => {
     const absolute = resolve(path);

package/dist/references/messages.js

@@ -3,6 +3,7 @@ const messages = {
         description: 'Discover and import Remix source references for the current cloud workspace',
         list: 'List verified local Remix references and their paths', search: 'Search accessible recommended or community Remixes',
         import: 'Import a fixed Remix source snapshot into the current engineering directory',
+        prepareStarterTemplate: 'Prepare a verified starter template in a temporary directory',
         query: 'Search names, branches, tags, creators or templates', source: 'recommended or community', project: 'Source project identifier', branch: 'Exact source branch',
         tag: 'Match a tag value; repeat to match any of the values', tagCategory: 'Tag category; defaults to Gameplay when --tag is used',
         workspace: 'Current cloud workspace identifier (must match this conversation)', directory: 'Current engineering directory (must match this conversation)',
@@ -22,6 +23,7 @@ const messages = {
     zh: {
         description: '为当前云工作区发现并导入 Remix 源码参考',
         list: '列出已验证的本地 Remix 参考及路径', search: '搜索可访问的推荐或社区 Remix', import: '把固定版本的 Remix 源码参考导入当前工程',
+        prepareStarterTemplate: '将经过校验的起始模板准备到临时目录',
         query: '搜索名称、分支、标签、创建者或模板', source: 'recommended（推荐）或 community（社区）', project: '来源项目标识', branch: '准确的来源分支名',
         tag: '匹配的标签值；可重复指定，匹配任意一个值', tagCategory: '标签分类；使用 --tag 时默认为 Gameplay',
         workspace: '当前云工作区标识（必须与本对话一致）', directory: '当前工程目录（必须与本对话一致）',

package/dist/references/protocol.js

@@ -3,18 +3,38 @@ import { z } from 'zod';
 const scope = {
     cwd: z.string().min(1).max(4096),
     workspaceId: z.string().uuid().optional(),
-    directoryName: z.string().regex(/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/).optional(),
+    directoryName: z
+        .string()
+        .regex(/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/)
+        .optional(),
 };
-export const remixReferenceToolRequestSchema = z.discriminatedUnion('action', [
+export const remixReferenceToolRequestSchema = z
+    .discriminatedUnion('action', [
     z.object({ ...scope, action: z.literal('list') }).strict(),
-    z.object({ ...scope, action: z.literal('search'), source: z.enum(['recommended', 'community']),
+    z.object({ ...scope, action: z.literal('prepare-starter-template') }).strict(),
+    z
+        .object({
+        ...scope,
+        action: z.literal('search'),
+        source: z.enum(['recommended', 'community']),
         tagCategory: z.string().trim().min(1).max(128).optional(),
         tagValues: z.array(z.string().trim().min(1).max(255)).min(1).max(20).optional(),
-        q: z.string().max(200).optional(), page: z.number().int().min(1).max(10000).default(1),
-        limit: z.number().int().min(1).max(50).default(12) }).strict(),
-    z.object({ ...scope, action: z.literal('import'), projectUuid: z.string().uuid(),
-        branchName: z.string().min(1).max(255) }).strict(),
-]).refine(input => input.action !== 'search' || (input.tagCategory === undefined) === (input.tagValues === undefined));
+        q: z.string().max(200).optional(),
+        page: z.number().int().min(1).max(10000).default(1),
+        limit: z.number().int().min(1).max(50).default(12),
+    })
+        .strict(),
+    z
+        .object({
+        ...scope,
+        action: z.literal('import'),
+        projectUuid: z.string().uuid(),
+        branchName: z.string().min(1).max(255),
+    })
+        .strict(),
+])
+    .refine((input) => input.action !== 'search' ||
+    (input.tagCategory === undefined) === (input.tagValues === undefined));
 export class RemixReferenceToolError extends Error {
     code;
     constructor(code) {
@@ -25,8 +45,15 @@ export class RemixReferenceToolError extends Error {
 }
 export function localRemixReference(root, reference) {
     const { files, omittedFiles, ...metadata } = reference;
-    return { ...metadata, source: { ...metadata.source,
-            recommended: metadata.source.recommended ?? metadata.source.category === 'recommended' },
-        resolvedPath: join(root, reference.path), fileCount: files.length,
-        omittedFileCount: omittedFiles?.length ?? 0 };
+    return {
+        ...metadata,
+        source: {
+            ...metadata.source,
+            recommended: ('recommended' in metadata.source ? metadata.source.recommended : undefined) ??
+                metadata.source.category === 'recommended',
+        },
+        resolvedPath: join(root, reference.path),
+        fileCount: files.length,
+        omittedFileCount: omittedFiles?.length ?? 0,
+    };
 }