castle-web-cli 0.4.92 → 0.4.93

package/dist/imports.js

@@ -0,0 +1,549 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { nanoid } from 'nanoid';
+import * as api from './api.js';
+import { runTar } from './save-deck.js';
+import { normalizeDeckPackageJson } from './normalize.js';
+import { getKitsDir } from './localPaths.js';
+// Adding another deck as a dependency (`castle-web add-import`; removing one is a
+// later command). Deliberately NOT `get-deck`: that one
+// replaces THIS deck's own source from the server (and carries guards for the
+// destruction that implies). Here the fetched deck is somebody else's, it lands in
+// a subdirectory, and nothing the deck already has is touched.
+//
+// Dependencies live in `imports/<alias>/` inside the deck. Real files, so the
+// engine's globs, the agent's greps, and vite all see them with no indirection.
+// They are READ-ONLY by policy (the files API refuses writes under `imports/`) --
+// a dependency is a reference to someone else's deck, so editing it in place would
+// mean editing their deck. Forking (keeping your own version of a dep's file) is a
+// later feature; copying a file out into the deck works meanwhile.
+//
+// `imports/` is excluded from the deck's saved source archive (see
+// SOURCE_ARCHIVE_EXCLUDES): the pins in castle.json are what identify a
+// dependency, and the files are re-fetchable from them -- same treatment
+// node_modules gets. That also means `get-deck` leaves an existing `imports/`
+// alone when it refreshes a deck.
+export const IMPORTS_DIR = 'imports';
+function readCastleJson(dir) {
+    const p = path.join(dir, 'castle.json');
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`Could not read ${p}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+// Only the `imports` key is ours; everything else in castle.json (deck identity,
+// editor config) is preserved as-is.
+function writeImportPin(dir, alias, pin) {
+    const existing = readCastleJson(dir) ?? {};
+    const next = {
+        ...existing,
+        imports: { ...(existing.imports ?? {}), [alias]: pin },
+    };
+    fs.writeFileSync(path.join(dir, 'castle.json'), JSON.stringify(next, null, 2) + '\n', 'utf-8');
+}
+// Aliases name the directory AND every path that references a dependency's files
+// (`imports/<alias>/drawings/rod.pxart`), so they have to be filesystem- and
+// URL-clean, and stable once chosen -- an alias is never re-derived from
+// upstream names, or renaming a deck upstream would break every ref to it here.
+function slugifyAlias(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40);
+}
+// An explicit `--as` may already be qualified (`someone.their-deck`); slugify
+// each part so the separator survives.
+function slugifyGivenAlias(name) {
+    return name
+        .split('.')
+        .map(slugifyAlias)
+        .filter(Boolean)
+        .join('.');
+}
+// Aliases are qualified by author -- `lovefromtom.fish-town` -- because deck
+// titles are not unique across users (nor even within one), and an import's name
+// is read far more often than it is typed. `.` rather than `:` or a second path
+// segment: a colon is illegal in Windows filenames and reads as `host:path` to
+// scp/rsync, and a nested directory would add a level to every files-panel tree
+// and every glob for a scope that is only occasionally interesting.
+//
+// Falls back to whatever is available: title alone, then the deck id.
+function qualifiedAlias(meta, deckId) {
+    const user = slugifyAlias(meta?.creator?.username ?? '');
+    const title = slugifyAlias(meta?.title ?? '');
+    if (user && title)
+        return `${user}.${title}`;
+    return title || slugifyAlias(deckId) || deckId;
+}
+// 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"
+// pattern (sed -i, most editors, most tooling) sails past a read-only FILE by
+// replacing it -- only a read-only DIRECTORY stops that. So both are locked.
+//
+// The cost is that `imports/<alias>` can't be deleted until it's unlocked, which
+// is why every path in this file that replaces a dependency unlocks it first.
+function chmodTree(dir, fileMode, dirMode) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const child = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            chmodTree(child, fileMode, dirMode);
+        else {
+            try {
+                fs.chmodSync(child, fileMode);
+            }
+            catch {
+                /* a file we can't chmod is not worth failing the import over */
+            }
+        }
+    }
+    // The directory goes last: its contents have to be reachable while we walk it.
+    try {
+        fs.chmodSync(dir, dirMode);
+    }
+    catch {
+        /* as above */
+    }
+}
+export function lockImportTree(dir) {
+    chmodTree(dir, 0o444, 0o555);
+}
+// Restore write permission so the tree can be replaced or removed. Directories
+// first, or their contents are unreachable.
+function unlockImportTree(dir) {
+    try {
+        fs.chmodSync(dir, 0o755);
+    }
+    catch {
+        return;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const child = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            unlockImportTree(child);
+        else {
+            try {
+                fs.chmodSync(child, 0o644);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+}
+// An import's code runs from the IMPORTING deck's node_modules -- there is one
+// install at the deck root, and a dependency's own node_modules is neither
+// fetched (it is excluded from the source archive) nor consulted. So whatever a
+// dependency declares has to be declared by the deck too.
+//
+// The deck's own declarations always win: this only ADDS packages the deck
+// doesn't already name, so a deliberate version choice is never overwritten by
+// an import. Nothing records which entries came from an import, so removing one
+// leaves its packages behind -- harmless (an unused package), and the honest
+// alternative needs provenance we don't track yet: once a deck starts importing
+// a package directly, "who added it" is no longer answerable from package.json.
+export function syncImportDependencies(deckDir) {
+    const deckPkgPath = path.join(deckDir, 'package.json');
+    let deckPkg;
+    try {
+        deckPkg = JSON.parse(fs.readFileSync(deckPkgPath, 'utf-8'));
+    }
+    catch {
+        return []; // no (or unreadable) package.json -- nothing to merge into
+    }
+    let aliases;
+    try {
+        aliases = fs.readdirSync(path.join(deckDir, IMPORTS_DIR)).sort();
+    }
+    catch {
+        return []; // no imports
+    }
+    const deps = { ...(deckPkg.dependencies ?? {}) };
+    const added = [];
+    for (const alias of aliases) {
+        let importPkg;
+        try {
+            importPkg = JSON.parse(fs.readFileSync(path.join(deckDir, IMPORTS_DIR, alias, 'package.json'), 'utf-8'));
+        }
+        catch {
+            continue; // an import without a package.json declares nothing
+        }
+        for (const [name, range] of Object.entries(importPkg.dependencies ?? {})) {
+            if (deps[name] !== undefined)
+                continue;
+            deps[name] = range;
+            added.push(`${name}@${range} (from ${alias})`);
+        }
+    }
+    if (added.length === 0)
+        return [];
+    deckPkg.dependencies = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+    fs.writeFileSync(deckPkgPath, JSON.stringify(deckPkg, null, 2) + '\n', 'utf-8');
+    // A dependency published from a checkout can carry `file:` refs that mean
+    // nothing here; normalize rewrites those to published ones.
+    normalizeDeckPackageJson(deckDir);
+    return added;
+}
+// `imports/` is derived state (it is excluded from the deck's archive), so a deck
+// that has been saved and fetched back -- the cloud's open-a-deck path, another
+// machine, a restored sandbox -- arrives with its pins but none of the files, and
+// won't run until they are back. Rebuilding them from the pins is `install`'s
+// job, alongside node_modules.
+export async function restoreMissingImports(deckDir) {
+    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const restored = [];
+    for (const [alias, pin] of Object.entries(pins)) {
+        const destDir = path.join(deckDir, IMPORTS_DIR, alias);
+        if (fs.existsSync(destDir))
+            continue;
+        if (pin?.deckId) {
+            const source = await api.webDeckSource(pin.deckId).catch(() => null);
+            if (!source) {
+                console.warn(`Could not fetch import "${alias}" (${pin.deckId}); it has no source on the server.`);
+                continue;
+            }
+            await fetchDeckSourceInto(source.archiveUrl, destDir);
+        }
+        else if (pin?.source === 'builtin') {
+            // Scaffolded from the kit shipped with the CLI: the same copy is still
+            // here, so there is nothing to fetch.
+            const kitDir = path.join(getKitsDir(), pin.kit ?? alias);
+            if (!fs.existsSync(kitDir)) {
+                console.warn(`Could not restore import "${alias}": this CLI ships no kit by that name.`);
+                continue;
+            }
+            fs.mkdirSync(path.dirname(destDir), { recursive: true });
+            fs.cpSync(kitDir, destDir, {
+                recursive: true,
+                verbatimSymlinks: true,
+                filter: (src) => src === kitDir || !['node_modules', '.castle', 'dist', '.git'].includes(path.basename(src)),
+            });
+        }
+        else {
+            console.warn(`Import "${alias}" has no deckId to fetch from; skipping.`);
+            continue;
+        }
+        lockImportTree(destDir);
+        restored.push(alias);
+    }
+    return restored;
+}
+// Download an archive and unpack it at `destDir`, via a temp dir so a failure
+// partway leaves nothing behind.
+async function fetchDeckSourceInto(archiveUrl, destDir) {
+    const res = await fetch(archiveUrl, { signal: AbortSignal.timeout(60000) });
+    if (!res.ok)
+        throw new Error(`Archive fetch failed: HTTP ${res.status}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    const tmpFile = path.join(os.tmpdir(), `castle-import-${nanoid(8)}.tar.gz`);
+    const tmpDir = path.join(os.tmpdir(), `castle-import-${nanoid(8)}`);
+    fs.writeFileSync(tmpFile, buf);
+    fs.mkdirSync(tmpDir, { recursive: true });
+    try {
+        await runTar(['-xzf', tmpFile, '-C', tmpDir]);
+        fs.mkdirSync(path.dirname(destDir), { recursive: true });
+        fs.renameSync(tmpDir, destDir);
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            /* nothing to clean */
+        }
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+// Checking every import means a request per import, so the answer is cached
+// briefly: the files panel asks on open and after any file change, and none of
+// those are reasons to re-ask the server.
+const STATUS_TTL_MS = 60_000;
+const statusCache = new Map();
+// What each import is pinned at, and whether the server has moved past it. A
+// deck's imports don't change under it -- an update is something the person
+// editing chooses -- so this only ever reports; taking the update is
+// `castle-web update-import`.
+export async function importStatuses(deckDir) {
+    const cached = statusCache.get(deckDir);
+    if (cached && Date.now() - cached.at < STATUS_TTL_MS)
+        return cached.value;
+    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const value = await Promise.all(Object.entries(pins).map(async ([alias, pin]) => {
+        const base = {
+            alias,
+            deckId: pin?.deckId ?? null,
+            version: pin?.version ?? '',
+            latest: null,
+            updateAvailable: false,
+            ...(pin?.via ? { via: pin.via } : {}),
+        };
+        // A kit copied from the CLI updates with the CLI; there is no deck to ask.
+        if (!pin?.deckId)
+            return base;
+        const source = await api.webDeckSource(pin.deckId).catch(() => null);
+        if (!source)
+            return base;
+        return {
+            ...base,
+            latest: source.updatedAt,
+            updateAvailable: source.updatedAt !== pin.version,
+        };
+    }));
+    statusCache.set(deckDir, { at: Date.now(), value });
+    return value;
+}
+// Taking or reverting an update makes the cached answer wrong immediately.
+function clearStatusCache(deckDir) {
+    statusCache.delete(deckDir);
+}
+// Place one deck's source at `imports/<alias>`, replacing whatever is there, and
+// record the pin. The tree is unpacked to a temp dir first so a fetch or tar that
+// fails partway leaves the deck untouched, and locked read-only afterwards.
+// The version an import is being replaced from, kept so an update can be undone
+// without the server's help -- it only ever has the latest archive, so once a
+// tree is overwritten the bytes are gone. One backup per import: enough for the
+// "update, playtest, undo if it broke something" loop, which is the case this
+// exists for.
+const BACKUPS_DIR = path.join('.castle', 'import-backups');
+function backupPath(deckDir, alias) {
+    return path.join(deckDir, BACKUPS_DIR, alias);
+}
+function backupImport(deckDir, alias) {
+    const src = path.join(deckDir, IMPORTS_DIR, alias);
+    if (!fs.existsSync(src))
+        return;
+    const dest = backupPath(deckDir, alias);
+    if (fs.existsSync(dest)) {
+        unlockImportTree(dest);
+        fs.rmSync(dest, { recursive: true, force: true });
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.cpSync(src, dest, { recursive: true, verbatimSymlinks: true });
+    const pin = (readCastleJson(deckDir)?.imports ?? {})[alias];
+    if (pin) {
+        fs.writeFileSync(path.join(dest, '.castle-import-pin.json'), JSON.stringify(pin, null, 2), 'utf-8');
+    }
+}
+async function placeImport(deckDir, alias, deckId, source, via) {
+    const destDir = path.join(deckDir, IMPORTS_DIR, alias);
+    const replaced = fs.existsSync(destDir);
+    if (replaced) {
+        backupImport(deckDir, alias);
+        unlockImportTree(destDir);
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    await fetchDeckSourceInto(source.archiveUrl, destDir);
+    lockImportTree(destDir);
+    clearStatusCache(deckDir);
+    writeImportPin(deckDir, alias, {
+        deckId,
+        version: source.updatedAt,
+        ...(via ? { via } : {}),
+    });
+    return { replaced };
+}
+// The imports of an import. A deck's own imports/ is left out of its archive, so
+// what arrives is its pins -- this follows them, flattening everything into ONE
+// imports/ at the deck root: a dependency's code refers to its own dependencies
+// by the path they sit at in the deck being served, and there is only one deck
+// being served.
+//
+// The alias is the one the depending deck recorded, because that is what its
+// refs are written against. Deterministic naming (`<author>.<deck>`) means two
+// decks depending on the same thing normally agree on the name by themselves;
+// where they don't, first one in wins and the second is reported rather than
+// silently renamed, since renaming would break the refs of whoever named it.
+async function addTransitiveImports(deckDir, viaAlias, seen) {
+    const viaDir = path.join(deckDir, IMPORTS_DIR, viaAlias);
+    const pins = (readCastleJson(viaDir)?.imports ?? {});
+    const added = [];
+    for (const [alias, pin] of Object.entries(pins)) {
+        if (!pin?.deckId || seen.has(pin.deckId))
+            continue;
+        const existing = (readCastleJson(deckDir)?.imports ?? {});
+        const holder = existing[alias];
+        if (holder && holder.deckId !== pin.deckId) {
+            console.warn(`"${viaAlias}" wants ${pin.deckId} as "${alias}", which is already ${holder.deckId} here -- skipping; ` +
+                `"${viaAlias}" may not work until one of them is re-imported under another name.`);
+            continue;
+        }
+        if (holder) {
+            seen.add(pin.deckId);
+            continue; // already have this one, at the name it expects
+        }
+        const source = await api.webDeckSource(pin.deckId).catch(() => null);
+        if (!source) {
+            console.warn(`"${viaAlias}" needs ${pin.deckId} ("${alias}"), which has no source on the server.`);
+            continue;
+        }
+        seen.add(pin.deckId);
+        await placeImport(deckDir, alias, pin.deckId, source, viaAlias);
+        added.push(alias);
+        added.push(...(await addTransitiveImports(deckDir, alias, seen)));
+    }
+    return added;
+}
+// Every deckId this deck already has, so a transitive walk doesn't refetch or
+// loop on a cycle.
+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 = {}) {
+    const targetDir = path.resolve(dir);
+    const deckId = options.deckId;
+    if (!deckId) {
+        console.error('No deck id. Usage: castle-web add-import <deckId> [dir] [--as ALIAS]');
+        process.exit(1);
+    }
+    if (!fs.existsSync(targetDir)) {
+        console.error(`No such directory: ${targetDir}`);
+        process.exit(1);
+    }
+    if (readCastleJson(targetDir)?.deckId === deckId) {
+        console.error(`Deck ${deckId} is this deck -- a deck can't import itself.`);
+        process.exit(1);
+    }
+    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);
+    }
+    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 { 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)
+        console.log(`Added dependency ${dep}`);
+    if (added.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)
+// at the version the server has now. Updates happen while editing, never on
+// someone else's behalf at play time -- the deck that gets published is one that
+// was run after the update, and `--revert` puts the previous version back if it
+// wasn't.
+export async function updateImport(dir, options = {}) {
+    const deckDir = path.resolve(dir);
+    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const aliases = options.alias ? [options.alias] : Object.keys(pins);
+    if (aliases.length === 0) {
+        console.log('This deck has no imports.');
+        return;
+    }
+    for (const alias of aliases) {
+        // Thrown, not exited: this runs inside the serve when the editor takes an
+        // update, and a bad name must not take the server down with it. The CLI's
+        // top-level handler turns it back into a message and a non-zero exit.
+        if (!pins[alias])
+            throw new Error(`No import named "${alias}" in this deck.`);
+    }
+    if (options.revert) {
+        for (const alias of aliases)
+            revertImport(deckDir, alias);
+        syncImportDependencies(deckDir);
+        return;
+    }
+    let changed = false;
+    for (const alias of aliases) {
+        const pin = pins[alias];
+        if (!pin.deckId) {
+            // A kit copied from the CLI updates with the CLI, not from the server.
+            if (options.alias)
+                console.log(`"${alias}" came with this CLI; it updates when the CLI does.`);
+            continue;
+        }
+        const source = await api.webDeckSource(pin.deckId).catch(() => null);
+        if (!source) {
+            console.warn(`Could not check "${alias}" (${pin.deckId}); it has no source on the server.`);
+            continue;
+        }
+        if (source.updatedAt === pin.version) {
+            console.log(`${alias} is up to date.`);
+            continue;
+        }
+        if (options.check) {
+            console.log(`${alias}: update available (have ${pin.version}, latest ${source.updatedAt})`);
+            changed = true;
+            continue;
+        }
+        await placeImport(deckDir, alias, pin.deckId, source, pin.via);
+        console.log(`Updated ${alias} (${pin.version} -> ${source.updatedAt})`);
+        // Its own dependencies may have moved too.
+        const transitive = await addTransitiveImports(deckDir, alias, importedDeckIds(deckDir));
+        for (const t of transitive)
+            console.log(`Also imported ${IMPORTS_DIR}/${t} (needed by ${alias})`);
+        changed = true;
+    }
+    if (!changed)
+        return;
+    if (options.check) {
+        console.log('Run `castle-web update-import` to take them.');
+        return;
+    }
+    const added = syncImportDependencies(deckDir);
+    for (const dep of added)
+        console.log(`Added dependency ${dep}`);
+    console.log('Play the deck to check the update before saving; `--revert` puts the old version back.');
+}
+// Restore the copy taken when this import was last replaced.
+function revertImport(deckDir, alias) {
+    const backup = backupPath(deckDir, alias);
+    if (!fs.existsSync(backup)) {
+        console.error(`No previous version of "${alias}" is kept here -- nothing to revert to.`);
+        return;
+    }
+    const destDir = path.join(deckDir, IMPORTS_DIR, alias);
+    if (fs.existsSync(destDir)) {
+        unlockImportTree(destDir);
+        fs.rmSync(destDir, { recursive: true, force: true });
+    }
+    fs.cpSync(backup, destDir, { recursive: true, verbatimSymlinks: true });
+    const pinFile = path.join(destDir, '.castle-import-pin.json');
+    if (fs.existsSync(pinFile)) {
+        try {
+            writeImportPin(deckDir, alias, JSON.parse(fs.readFileSync(pinFile, 'utf-8')));
+        }
+        catch {
+            /* an unreadable pin file just means the version stays as recorded */
+        }
+        fs.rmSync(pinFile, { force: true });
+    }
+    unlockImportTree(backup);
+    fs.rmSync(backup, { recursive: true, force: true });
+    lockImportTree(destDir);
+    clearStatusCache(deckDir);
+    console.log(`Reverted ${alias} to its previous version.`);
+}

package/dist/index.js

@@ -5,9 +5,9 @@ import { login } from './login.js';
 import { serve } from './serve.js';
 import { saveDeck } from './save-deck.js';
 import { getDeck } from './get-deck.js';
+import { addImport, updateImport } from './imports.js';
 import { init } from './init.js';
 import { install } from './install.js';
-import { pull } from './pull.js';
 import { connectWS, savePreviewImage, savePreviewIfNeeded, takeScreenshot } from './preview.js';
 const args = process.argv.slice(2);
 const command = args[0];
@@ -20,6 +20,7 @@ const FLAGS_WITH_VALUES = new Set([
     '--title',
     '--caption',
     '--visibility',
+    '--as',
 ]);
 function findPositionalDir() {
     for (let i = 1; i < args.length; i++) {
@@ -32,6 +33,21 @@ function findPositionalDir() {
     }
     return '.';
 }
+// Every positional after the command, in order (flags and their values skipped).
+// `import` takes two (the deck id, then the importing deck's dir); every other
+// command takes at most one and uses findPositionalDir.
+function readPositionals() {
+    const out = [];
+    for (let i = 1; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            if (FLAGS_WITH_VALUES.has(args[i]))
+                i++;
+            continue;
+        }
+        out.push(args[i]);
+    }
+    return out;
+}
 function getFlagValue(flag) {
     const idx = args.indexOf(flag);
     return idx >= 0 ? args[idx + 1] : undefined;
@@ -65,8 +81,9 @@ function usage() {
   castle-web screenshot [--out FILE] [--port PORT]
   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]
-  castle-web pull [dir] [--deck-id ID] [--force]
+  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 update-import [alias] [dir] [--check] [--revert]   (re-fetches imports; no alias means all)
   castle-web install [dir]
   castle-web login
 
@@ -112,24 +129,37 @@ async function main() {
             break;
         }
         case 'get-deck': {
-            const dir = findPositionalDir();
-            if (dir === '.') {
-                console.error('Usage: castle-web get-deck <dir> [--deck-id ID]');
-                process.exit(1);
-            }
-            const deckId = getFlagValue('--deck-id');
-            await getDeck(dir, { deckId });
-            break;
-        }
-        case 'pull': {
-            await pull(findPositionalDir(), {
+            // `.` is allowed: refreshing the deck you're standing in is the in-place case,
+            // and a cwd that isn't a deck fails on deckId resolution anyway.
+            await getDeck(findPositionalDir(), {
                 deckId: getFlagValue('--deck-id'),
                 force: hasFlag('--force'),
             });
             break;
         }
+        case 'add-import': {
+            // The deck id 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],
+                alias: getFlagValue('--as'),
+            });
+            break;
+        }
+        case 'update-import': {
+            // `castle-web update-import [alias] [dir]` -- no alias updates every import.
+            const positionals = readPositionals();
+            const alias = positionals[0];
+            await updateImport(positionals[1] ?? (alias && !alias.includes('/') ? '.' : alias) ?? '.', {
+                alias,
+                check: hasFlag('--check'),
+                revert: hasFlag('--revert'),
+            });
+            break;
+        }
         case 'install': {
-            install(findPositionalDir());
+            await install(findPositionalDir());
             break;
         }
         case 'restart': {