@openstory/cli 0.0.0-stage → 0.1.0

package/dist/sync.js

@@ -0,0 +1,355 @@
+/**
+ * `openstory sync`: a one-way mirror of an organization's sequences into
+ * `<dir>/<organization>/<sequence-slug>/` (#2222). OpenStory writes; the folder
+ * is output only and nothing reads it back. A full pass runs at start, then a
+ * sequence is synced again a couple of seconds after its realtime events
+ * settle. Every pass is safe to repeat, so a missed event is fixed by the next.
+ *
+ * `<dir>/.openstory/sync.json` maps organization and sequence ids to folders,
+ * so a slug change renames the folder. Archived or deleted sequences drop out
+ * of the list and their folders are left alone.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { recordOf, stringOf } from './api.js';
+import { downloadSequenceAssets } from './assets.js';
+import { parseOrigin } from './context.js';
+import { isMissingFile, openStoryApiKey, signIn } from './login.js';
+const SETTLE_MS = 2000;
+const RELIST_MS = 60_000;
+/** The realtime route takes at most this many channels per connection. */
+const MAX_CHANNELS = 64;
+function parseSync(args, home, cwd) {
+    const { origin, rest } = parseOrigin(args);
+    let dir = join(home, 'openstory');
+    let once = false;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i] ?? '';
+        if (arg === '--dir') {
+            const value = rest[i + 1];
+            if (value === undefined || value.startsWith('-')) {
+                throw new Error('--dir needs a directory');
+            }
+            dir = resolve(cwd, value);
+            i += 1;
+        }
+        else if (arg === '--once')
+            once = true;
+        else
+            throw new Error(`Unknown argument: ${arg}`);
+    }
+    return { origin, dir, once };
+}
+const stateFile = (dir) => join(dir, '.openstory', 'sync.json');
+export async function readSyncState(dir, origin) {
+    let text;
+    try {
+        text = await readFile(stateFile(dir), 'utf8');
+    }
+    catch (error) {
+        // Only a missing file is a first run; anything else would lose the folder map.
+        if (isMissingFile(error)) {
+            return { v: 1, origin, organizations: {}, sequences: {} };
+        }
+        throw new Error(`${stateFile(dir)} is unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = recordOf(JSON.parse(text));
+    }
+    catch {
+        throw new Error(`${stateFile(dir)} is not JSON; fix or remove it`);
+    }
+    if (parsed.origin !== origin) {
+        throw new Error(`${dir} mirrors ${String(parsed.origin)}. Pick another --dir for ${origin}.`);
+    }
+    const sequences = {};
+    for (const [id, value] of Object.entries(recordOf(parsed.sequences))) {
+        const row = recordOf(value);
+        if (typeof row.organization === 'string' &&
+            typeof row.folder === 'string') {
+            sequences[id] = { organization: row.organization, folder: row.folder };
+        }
+    }
+    const organizations = {};
+    for (const [id, folder] of Object.entries(recordOf(parsed.organizations))) {
+        if (typeof folder === 'string')
+            organizations[id] = folder;
+    }
+    return { v: 1, origin, organizations, sequences };
+}
+async function writeSyncState(dir, state) {
+    const file = stateFile(dir);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(`${file}.partial`, `${JSON.stringify(state, null, 2)}\n`);
+    await rename(`${file}.partial`, file);
+}
+/** Moves `from` to `to` under `dir`; both present is a clash the user settles. */
+async function renameFolder(dir, from, to) {
+    if (from === to)
+        return;
+    const source = join(dir, from);
+    const target = join(dir, to);
+    if (!existsSync(source))
+        return;
+    if (existsSync(target)) {
+        throw new Error(`${source} was renamed to ${target}, which already exists. Move or delete one, then sync again.`);
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await rename(source, target);
+}
+/** One folder name segment: never a path, never hidden. */
+function folderName(value) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+        throw new Error(`OpenStory answered with an unusable folder name: ${value}`);
+    }
+    return value;
+}
+class Mirror {
+    context;
+    args;
+    state;
+    key = null;
+    organization = null;
+    constructor(context, args, state) {
+        this.context = context;
+        this.args = args;
+        this.state = state;
+    }
+    auth() {
+        return { ...this.context, origin: this.args.origin };
+    }
+    /** A GET with the stored key; a 401 signs in once more. */
+    async get(path) {
+        this.key ??= await openStoryApiKey(this.auth());
+        const run = (key) => this.context.fetch(new URL(path, this.args.origin), {
+            headers: { authorization: `Bearer ${key}` },
+        });
+        let response = await run(this.key);
+        if (response.status === 401) {
+            this.key = await signIn(this.auth());
+            response = await run(this.key);
+        }
+        return response;
+    }
+    async json(path) {
+        const response = await this.get(path);
+        if (!response.ok) {
+            throw new Error(`OpenStory answered ${response.status} for ${path}`);
+        }
+        return recordOf(await response.json());
+    }
+    /** The key's organization folder: `personal` for the sign-up one, else its slug. */
+    async syncOrganization() {
+        const org = await this.json('/api/v1/organization');
+        const id = stringOf(org.id, 'an organization id');
+        const folder = org.personal === true
+            ? 'personal'
+            : folderName(stringOf(org.slug, 'an organization slug'));
+        const previous = this.state.organizations[id];
+        if (previous !== undefined) {
+            await renameFolder(this.args.dir, previous, folder);
+            for (const row of Object.values(this.state.sequences)) {
+                if (row.organization === id) {
+                    row.folder = join(folder, row.folder.slice(previous.length + 1));
+                }
+            }
+        }
+        this.state.organizations[id] = folder;
+        this.organization = { id, folder };
+        await writeSyncState(this.args.dir, this.state);
+        return folder;
+    }
+    async listSequences() {
+        const found = [];
+        let path = '/api/v1/sequences?limit=100';
+        while (path !== null) {
+            const page = await this.json(path);
+            const rows = page.sequences;
+            if (!Array.isArray(rows)) {
+                throw new Error(`OpenStory answered without a sequence list for ${path}`);
+            }
+            for (const value of rows) {
+                const row = recordOf(value);
+                found.push({
+                    id: stringOf(row.id, 'a sequence id'),
+                    slug: folderName(stringOf(row.slug, 'a sequence slug')),
+                });
+            }
+            const next = recordOf(recordOf(page._links).next).href;
+            path = typeof next === 'string' ? next : null;
+        }
+        return found;
+    }
+    /** One sequence's id and slug; null once it is archived or deleted. */
+    async getSequence(id) {
+        const response = await this.get(`/api/v1/sequences/${encodeURIComponent(id)}`);
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            throw new Error(`OpenStory answered ${response.status} for ${id}`);
+        }
+        const row = recordOf(await response.json());
+        if (row.status === 'archived')
+            return null;
+        return {
+            id: stringOf(row.id, 'a sequence id'),
+            slug: folderName(stringOf(row.slug, 'a sequence slug')),
+        };
+    }
+    async syncSequence(sequence) {
+        const organization = this.organization;
+        if (organization === null)
+            throw new Error('Sync the organization first');
+        const folder = join(organization.folder, sequence.slug);
+        const previous = this.state.sequences[sequence.id];
+        if (previous)
+            await renameFolder(this.args.dir, previous.folder, folder);
+        this.state.sequences[sequence.id] = {
+            organization: organization.id,
+            folder,
+        };
+        await writeSyncState(this.args.dir, this.state);
+        const result = await downloadSequenceAssets({
+            sequenceId: sequence.id,
+            origin: this.args.origin,
+            cacheDir: join(this.args.dir, '.openstory', 'cache'),
+            dest: join(this.args.dir, folder),
+            history: false,
+            includeExports: false,
+            fetch: this.context.fetch,
+            key: async () => (this.key ??= await openStoryApiKey(this.auth())),
+            refresh: async () => (this.key = await signIn(this.auth())),
+        });
+        if (result.saved + result.removed > 0) {
+            this.context.stdout.write(`${folder}: saved ${result.saved}, removed ${result.removed}\n`);
+        }
+    }
+    /** Startup pass: every listed sequence, unchanged files skipped. */
+    async fullPass() {
+        await this.syncOrganization();
+        const sequences = await this.listSequences();
+        for (const sequence of sequences)
+            await this.syncSequence(sequence);
+        return sequences;
+    }
+}
+/** The ids each `data:` frame of an SSE chunk names as its channel. */
+export function channelsInFrames(text) {
+    const channels = [];
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('data:'))
+            continue;
+        try {
+            const channel = recordOf(JSON.parse(line.slice(5))).channel;
+            if (typeof channel === 'string')
+                channels.push(channel);
+        }
+        catch {
+            // A partial or non-JSON frame carries no channel.
+        }
+    }
+    return channels;
+}
+/** Runs `job` once per id, `SETTLE_MS` after its last event, one job at a time. */
+export function settler(job, onError, settleMs = SETTLE_MS) {
+    const timers = new Map();
+    let chain = Promise.resolve();
+    return (id) => {
+        clearTimeout(timers.get(id));
+        timers.set(id, setTimeout(() => {
+            timers.delete(id);
+            chain = chain.then(() => job(id)).catch(onError);
+        }, settleMs));
+    };
+}
+async function watch(mirror, start, context) {
+    let sequences = new Map(start.map((s) => [s.id, s]));
+    const report = (error) => context.stderr.write(`sync: ${error instanceof Error ? error.message : String(error)}\n`);
+    const resync = settler(async (id) => {
+        if (!sequences.has(id))
+            return;
+        // The current slug, so a rename moves the folder now, not at the next list.
+        const sequence = await mirror.getSequence(id);
+        if (sequence)
+            await mirror.syncSequence(sequence);
+    }, report);
+    let abort = new AbortController();
+    // ponytail: one connection with the newest 64 sequences; older ones resync on the next start.
+    const listen = async () => {
+        for (let delay = 1000;; delay = Math.min(delay * 2, 30_000)) {
+            const ids = [...sequences.keys()].slice(0, MAX_CHANNELS);
+            const signal = abort.signal;
+            try {
+                if (ids.length > 0) {
+                    const response = await mirror.get(`/api/realtime?channels=${ids.map(encodeURIComponent).join(',')}`);
+                    if (!response.ok || !response.body) {
+                        throw new Error(`realtime answered ${response.status}`);
+                    }
+                    delay = 1000;
+                    const reader = response.body.getReader();
+                    signal.addEventListener('abort', () => void reader.cancel());
+                    if (signal.aborted)
+                        void reader.cancel();
+                    const decoder = new TextDecoder();
+                    let buffer = '';
+                    for (;;) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        buffer += decoder.decode(value, { stream: true });
+                        const end = buffer.lastIndexOf('\n\n');
+                        if (end === -1)
+                            continue;
+                        for (const id of channelsInFrames(buffer.slice(0, end))) {
+                            resync(id);
+                        }
+                        buffer = buffer.slice(end + 2);
+                    }
+                }
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    report(error);
+            }
+            if (!signal.aborted) {
+                await new Promise((r) => setTimeout(r, ids.length ? delay : RELIST_MS));
+            }
+        }
+    };
+    void listen();
+    for (;;) {
+        await new Promise((r) => setTimeout(r, RELIST_MS));
+        try {
+            await mirror.syncOrganization();
+            const listed = await mirror.listSequences();
+            const added = listed.filter((s) => {
+                const known = sequences.get(s.id);
+                return known === undefined || known.slug !== s.slug;
+            });
+            sequences = new Map(listed.map((s) => [s.id, s]));
+            for (const sequence of added)
+                resync(sequence.id);
+            if (added.length > 0) {
+                abort.abort();
+                abort = new AbortController();
+            }
+        }
+        catch (error) {
+            report(error);
+        }
+    }
+}
+export const sync = {
+    usage: 'openstory sync [--dir dir] [--once] [--origin url]',
+    async run(args, context) {
+        const request = parseSync(args, context.home, context.cwd);
+        const state = await readSyncState(request.dir, request.origin);
+        const mirror = new Mirror(context, request, state);
+        const sequences = await mirror.fullPass();
+        context.stdout.write(`Synced ${sequences.length} sequences into ${request.dir}\n`);
+        if (!request.once)
+            await watch(mirror, sequences, context);
+    },
+};

package/dist/update-notice.d.ts

@@ -0,0 +1,13 @@
+/** At most one npm registry check a day; a newer version becomes a one-line hint. Never updates itself. */
+export type UpdateCheckOptions = {
+    home: string;
+    current: string;
+    now: number;
+    /** Plain fetch: the registry never gets the OpenStory version header. */
+    fetch: typeof fetch;
+    timeoutMs?: number;
+};
+/** The hint to print, or null. Swallows every error. */
+export declare function updateNotice(options: UpdateCheckOptions): Promise<string | null>;
+/** `a` > `b` on major.minor.patch; anything unreadable is not newer. */
+export declare function isNewer(a: string, b: string): boolean;

package/dist/update-notice.js

@@ -0,0 +1,55 @@
+/** At most one npm registry check a day; a newer version becomes a one-line hint. Never updates itself. */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { recordOf } from './api.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_URL = 'https://registry.npmjs.org/@openstory/cli/latest';
+const CACHE_FILE = ['.openstory', 'cli-update.json'];
+/** The hint to print, or null. Swallows every error. */
+export async function updateNotice(options) {
+    try {
+        const latest = await latestVersion(options);
+        return latest !== null && isNewer(latest, options.current)
+            ? `openstory ${latest} is out (you have ${options.current}): npx @openstory/cli@latest\n`
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function latestVersion(options) {
+    const file = join(options.home, ...CACHE_FILE);
+    const cached = recordOf(JSON.parse(await readFile(file, 'utf8').catch(() => '{}')));
+    const cachedLatest = typeof cached.latest === 'string' ? cached.latest : null;
+    if (typeof cached.checkedAt === 'number' &&
+        options.now - cached.checkedAt < DAY_MS) {
+        return cachedLatest;
+    }
+    // Stamp first, so a failed or slow check still waits a day.
+    await mkdir(join(options.home, CACHE_FILE[0]), { recursive: true });
+    await writeFile(file, JSON.stringify({ checkedAt: options.now, latest: cachedLatest }));
+    const response = await options.fetch(REGISTRY_URL, {
+        signal: AbortSignal.timeout(options.timeoutMs ?? 1500),
+    });
+    if (!response.ok)
+        return cachedLatest;
+    const latest = recordOf(await response.json()).version;
+    if (typeof latest !== 'string')
+        return cachedLatest;
+    await writeFile(file, JSON.stringify({ checkedAt: options.now, latest }));
+    return latest;
+}
+/** `a` > `b` on major.minor.patch; anything unreadable is not newer. */
+export function isNewer(a, b) {
+    const parse = (v) => /^(\d+)\.(\d+)\.(\d+)/.exec(v)?.slice(1).map(Number);
+    const x = parse(a);
+    const y = parse(b);
+    if (!x || !y)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d > 0;
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@openstory/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The OpenStory command line: sign in, download a sequence's files, and share a cut.",
+  "keywords": [
+    "cli",
+    "openstory",
+    "stitch",
+    "video"
+  ],
+  "homepage": "https://github.com/openstory-so/openstory/tree/main/packages/cli#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openstory-so/openstory.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "openstory": "./bin/openstory.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@openstory/stitch": "workspace:^"
+  }
+}