castle-web-cli 0.4.110 → 0.4.112

package/dist/imports.js

@@ -25,6 +25,37 @@ import { readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
 // node_modules gets. That also means `get-deck` leaves an existing `imports/`
 // alone when it refreshes a deck.
 export const IMPORTS_DIR = 'imports';
+export class ImportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ImportError';
+        this.code = code;
+    }
+}
+// What someone has in hand is a deck id or the URL of the page they were just
+// looking at, so both are accepted here rather than in a separate resolve step.
+// Recognized: a bare id, a deck page (`castle.xyz/d/<id>`), and the cloud editor
+// (`castle.xyz/admin/cloud/<id>`) -- for anything else the last path segment is
+// tried, since every castle deck URL ends in the id.
+export function parseDeckRef(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    if (!trimmed.includes('/'))
+        return api.isDeckIdShaped(trimmed) ? trimmed : null;
+    let url;
+    try {
+        url = new URL(trimmed.includes('://') ? trimmed : `https://${trimmed}`);
+    }
+    catch {
+        return null;
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    const afterD = segments.indexOf('d');
+    const candidate = afterD >= 0 ? segments[afterD + 1] : segments[segments.length - 1];
+    return candidate && api.isDeckIdShaped(candidate) ? candidate : null;
+}
 // Only the `imports` key is ours; everything else in castle.json (deck identity,
 // editor config) is preserved as-is.
 function writeImportPin(dir, alias, pin) {
@@ -70,6 +101,25 @@ function qualifiedAlias(meta, deckId) {
         return `${user}.${title}`;
     return title || slugifyAlias(deckId) || deckId;
 }
+// A derived alias can already be taken -- two people with a same-named deck, or
+// the same title twice. Reusing it would silently replace a different
+// dependency, so a taken name gets a number. A name already pointing at THIS
+// deck is not a collision: that one is the update case, and keeping it is what
+// makes re-importing a deck update it in place.
+const MAX_ALIAS_ATTEMPTS = 100;
+function availableAlias(deckDir, alias, deckId) {
+    const pins = readCastleJson(deckDir)?.imports ?? {};
+    const taken = (name) => pins[name] !== undefined
+        ? pins[name].deckId !== deckId
+        : fs.existsSync(path.join(deckDir, IMPORTS_DIR, name));
+    if (!taken(alias))
+        return alias;
+    for (let n = 2; n <= MAX_ALIAS_ATTEMPTS; n++) {
+        if (!taken(`${alias}-${n}`))
+            return `${alias}-${n}`;
+    }
+    throw new ImportError('bad-alias', `Too many imports already named "${alias}"; pass --as to name this one.`);
+}
 // Dependencies are made read-only ON DISK, not just refused by the files API.
 // The API guard only covers the editor; an agent or a shell command writes
 // straight to the filesystem, and the common "write a temp file and rename it"
@@ -386,49 +436,71 @@ async function addTransitiveImports(deckDir, viaAlias, seen) {
 }
 // Every deckId this deck already has, so a transitive walk doesn't refetch or
 // loop on a cycle.
-function importedDeckIds(deckDir) {
+export function importedDeckIds(deckDir) {
     const pins = readCastleJson(deckDir)?.imports ?? {};
     return new Set(Object.values(pins).map((p) => p?.deckId).filter((id) => !!id));
 }
-export async function addImport(dir, options = {}) {
+// The import itself. Throws ImportError rather than exiting, because this also
+// runs inside the serve (from the editor's Import panel), where taking the
+// process down is not an option. The CLI wrapper below prints and exits.
+export async function addImportTo(dir, options = {}) {
     const targetDir = path.resolve(dir);
-    const deckId = options.deckId;
+    const ref = options.deckRef?.trim();
+    if (!ref) {
+        throw new ImportError('no-deck-ref', 'No deck given. Pass a deck id or a castle.xyz deck link.');
+    }
+    const deckId = parseDeckRef(ref);
     if (!deckId) {
-        console.error('No deck id. Usage: castle-web add-import <deckId> [dir] [--as ALIAS]');
-        process.exit(1);
+        throw new ImportError('bad-deck-ref', `Not a deck id or a castle deck link: ${ref}`);
     }
     if (!fs.existsSync(targetDir)) {
-        console.error(`No such directory: ${targetDir}`);
-        process.exit(1);
+        throw new ImportError('no-such-dir', `No such directory: ${targetDir}`);
     }
     if (readCastleJson(targetDir)?.deckId === deckId) {
-        console.error(`Deck ${deckId} is this deck -- a deck can't import itself.`);
-        process.exit(1);
+        throw new ImportError('self-import', `Deck ${deckId} is this deck -- a deck can't import itself.`);
     }
     const [source, meta] = await Promise.all([
         api.webDeckSource(deckId),
         api.deckMeta(deckId).catch(() => null),
     ]);
     if (!source) {
-        console.error(`No source archive on the server for deck ${deckId}.`);
-        console.error(`Its owner needs to run \`castle-web save-deck\` before it can be imported.`);
-        process.exit(1);
+        throw new ImportError('no-source', `No source archive on the server for deck ${deckId}. ` +
+            'Its owner needs to run `castle-web save-deck` before it can be imported.');
     }
-    const alias = options.alias ? slugifyGivenAlias(options.alias) : qualifiedAlias(meta, deckId);
-    if (!alias) {
-        console.error(`Could not derive a usable name from --as; pick one with letters or digits.`);
-        process.exit(1);
+    const given = options.alias ? slugifyGivenAlias(options.alias) : '';
+    if (options.alias && !given) {
+        throw new ImportError('bad-alias', 'Could not derive a usable name; pick one with letters or digits.');
     }
+    // An explicit `--as` is the caller's call, collision and all. A derived one
+    // gets a number instead, since nothing asked for that particular name.
+    const alias = given || availableAlias(targetDir, qualifiedAlias(meta, deckId), deckId);
     const { replaced } = await placeImport(targetDir, alias, deckId, source);
-    console.log(`${replaced ? 'Updated' : 'Imported'} ${deckId} at ${IMPORTS_DIR}/${alias} (read-only on disk).`);
-    const seen = importedDeckIds(targetDir);
-    const transitive = await addTransitiveImports(targetDir, alias, seen);
-    for (const t of transitive)
-        console.log(`Also imported ${IMPORTS_DIR}/${t} (needed by ${alias})`);
-    const added = syncImportDependencies(targetDir);
-    for (const dep of added)
+    const transitive = await addTransitiveImports(targetDir, alias, importedDeckIds(targetDir));
+    const dependencies = syncImportDependencies(targetDir);
+    return { deckId, alias, replaced, transitive, dependencies };
+}
+export async function addImport(dir, options = {}) {
+    let result;
+    try {
+        result = await addImportTo(dir, options);
+    }
+    catch (err) {
+        if (!(err instanceof ImportError))
+            throw err;
+        console.error(err.message);
+        if (err.code === 'no-deck-ref') {
+            console.error('Usage: castle-web add-import <deckId|url> [dir] [--as ALIAS]');
+        }
+        process.exit(1);
+    }
+    console.log(`${result.replaced ? 'Updated' : 'Imported'} ${result.deckId} at ` +
+        `${IMPORTS_DIR}/${result.alias} (read-only on disk).`);
+    for (const t of result.transitive) {
+        console.log(`Also imported ${IMPORTS_DIR}/${t} (needed by ${result.alias})`);
+    }
+    for (const dep of result.dependencies)
         console.log(`Added dependency ${dep}`);
-    if (added.length > 0)
+    if (result.dependencies.length > 0)
         console.log('Run `castle-web install` to install them.');
 }
 // `castle-web update-import [alias] [dir]`: re-fetch an import (or all of them)

package/dist/index.js

@@ -6,6 +6,7 @@ import { serve } from './serve.js';
 import { saveDeck } from './save-deck.js';
 import { getDeck } from './get-deck.js';
 import { addImport, updateImport } from './imports.js';
+import { listDecks } from './list-decks.js';
 import { getCliVersion, init } from './init.js';
 import { install } from './install.js';
 import { connectWS, savePreviewImage, savePreviewIfNeeded, takeScreenshot } from './preview.js';
@@ -21,6 +22,7 @@ const FLAGS_WITH_VALUES = new Set([
     '--caption',
     '--visibility',
     '--as',
+    '--kind',
 ]);
 function findPositionalDir() {
     for (let i = 1; i < args.length; i++) {
@@ -82,7 +84,8 @@ function usage() {
   castle-web save-preview-image [dir] [--port PORT] [--no-restart]
   castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private]
   castle-web get-deck [dir] [--deck-id ID] [--force]   (replaces the source if the deck is already there)
-  castle-web add-import <deckId> [dir] [--as ALIAS]   (adds another deck as a read-only dependency in imports/)
+  castle-web list-decks [dir] [--kind mine|saved|kits]   (decks this one could import; ids are what add-import takes)
+  castle-web add-import <deckId|url> [dir] [--as ALIAS]   (adds another deck as a read-only dependency in imports/)
   castle-web update-import [alias] [dir] [--check] [--revert]   (re-fetches imports; no alias means all)
   castle-web install [dir]
   castle-web login
@@ -146,12 +149,16 @@ async function main() {
             });
             break;
         }
+        case 'list-decks': {
+            await listDecks(findPositionalDir(), { kind: getFlagValue('--kind') });
+            break;
+        }
         case 'add-import': {
-            // The deck id is the first positional; the importing deck's dir is an
-            // optional second, defaulting to the cwd.
+            // The deck -- an id or the link to its page -- is the first positional;
+            // the importing deck's dir is an optional second, defaulting to the cwd.
             const positionals = readPositionals();
             await addImport(positionals[1] ?? '.', {
-                deckId: getFlagValue('--deck-id') ?? positionals[0],
+                deckRef: getFlagValue('--deck-id') ?? positionals[0],
                 alias: getFlagValue('--as'),
             });
             break;

package/dist/list-decks.d.ts

@@ -0,0 +1,3 @@
+export declare function listDecks(dir: string, options?: {
+    kind?: string;
+}): Promise<void>;

package/dist/list-decks.js

@@ -0,0 +1,44 @@
+// `castle-web list-decks` -- what this deck could import, for an agent rather
+// than for the editor's picker. Same answer the picker gets (importBrowse's
+// `/__castle/import/*` backend), printed one deck per line.
+//
+// The agent needs this because `add-import` takes a deck id, and until now
+// nothing told it which ids exist -- so it could only import a deck the user
+// had already named.
+import * as path from 'path';
+import { listImportable } from './importBrowse.js';
+const KINDS = ['mine', 'saved', 'kits'];
+function isKind(value) {
+    return KINDS.includes(value);
+}
+// One deck per line, id first: the id is what `add-import` takes, so it reads
+// straight out of the listing without the agent having to parse a sentence.
+function formatDeck(deck) {
+    const parts = [deck.deckId, deck.title];
+    if (deck.creator)
+        parts.push(`@${deck.creator}`);
+    if (deck.imported)
+        parts.push('(already imported)');
+    return parts.join('  ');
+}
+export async function listDecks(dir, options = {}) {
+    const kind = options.kind ?? 'mine';
+    if (!isKind(kind)) {
+        console.error(`Unknown kind "${kind}". Use one of: ${KINDS.join(', ')}.`);
+        process.exit(1);
+    }
+    const list = await listImportable(path.resolve(dir), kind);
+    if (!list.signedIn) {
+        console.error('Not signed in. Run `castle-web login` first.');
+        process.exit(1);
+    }
+    if (list.decks.length === 0) {
+        console.log(`No ${kind} decks with source files to import.`);
+        return;
+    }
+    for (const deck of list.decks)
+        console.log(formatDeck(deck));
+    if (list.truncated) {
+        console.log(`(first ${list.decks.length}; there are more)`);
+    }
+}

package/dist/save-deck.d.ts

@@ -1,5 +1,7 @@
 export declare const SOURCE_ARCHIVE_EXCLUDES: string[];
-export declare function runTar(args: string[]): Promise<void>;
+export declare function runTar(args: string[], opts?: {
+    capture?: boolean;
+}): Promise<string>;
 export declare function archiveSource(projectDir: string): Promise<Buffer>;
 export type SaveVisibility = 'unlisted' | 'private';
 export interface SaveDeckOptions {

package/dist/save-deck.js

@@ -12,10 +12,14 @@ import { bundleProject } from './bundle.js';
 // part of it. (Being on this list also means `get-deck` leaves an existing
 // `imports/` in place when it refreshes a deck.)
 export const SOURCE_ARCHIVE_EXCLUDES = ['node_modules', 'dist', '.castle', '.git', 'imports'];
-export function runTar(args) {
+// `capture` keeps tar's stdout and resolves with it -- for listing an archive
+// (`-tzf`), where the output IS the answer. Packing and unpacking ignore it.
+export function runTar(args, opts = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn('tar', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        const child = spawn('tar', args, { stdio: ['ignore', opts.capture ? 'pipe' : 'ignore', 'pipe'] });
+        let stdout = '';
         let stderr = '';
+        child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
         child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
         child.on('error', reject);
         child.on('close', (code) => {
@@ -23,7 +27,7 @@ export function runTar(args) {
                 reject(new Error(`tar exited with code ${code}: ${stderr}`));
                 return;
             }
-            resolve();
+            resolve(stdout);
         });
     });
 }

package/dist/serve.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { spawn } from 'child_process';
 import { createServer } from 'vite';
 import { WebSocketServer, WebSocket } from 'ws';
-import { createIdeServer } from './ide.js';
+import { createIdeServer, FAVICON_LINK_TAGS } from './ide.js';
 import { createAgentServer } from './agent.js';
 import { sceneFilesPlugin, importsAliasPlugin } from './vitePlugins.js';
 import { installFilesChangedWatcher } from './filesChanged.js';
@@ -58,7 +58,15 @@ function castlePlugin(wsPort, ideServer, agentServer) {
         transformIndexHtml: {
             order: 'pre',
             handler(html) {
-                return html.replace(/<head(\s[^>]*)?>/i, (match) => `${match}\n    <script>window.CastleEmbed={edit:true,host:'dev'};</script>\n    ${CONSOLE_CAPTURE}`);
+                // Give the deck page Castle's favicon too -- it's a real page when
+                // opened directly (play surface / `?edit=0`), not just the editor's
+                // iframe. Injected here rather than in the kit templates so bare
+                // `--kit none` decks and already-scaffolded decks get it as well; a
+                // deck that declares its own icon keeps it.
+                const favicon = /<link[^>]+rel=["']?[^"'>]*icon/i.test(html)
+                    ? ''
+                    : `\n    ${FAVICON_LINK_TAGS}`;
+                return html.replace(/<head(\s[^>]*)?>/i, (match) => `${match}${favicon}\n    <script>window.CastleEmbed={edit:true,host:'dev'};</script>\n    ${CONSOLE_CAPTURE}`);
             },
         },
         configureServer(server) {