@shuffl/cli 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export interface CliIO {
+    env: NodeJS.ProcessEnv;
+    stdin: () => Promise<string>;
+    stdout: (value: string) => void;
+    stderr: (value: string) => void;
+}
+export declare function runCli(args: string[], io?: CliIO): Promise<number>;

package/dist/index.js

@@ -0,0 +1,207 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, writeFile, } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { createShuffl, ORPCError } from '@shuffl/sdk';
+import { commands } from './commands.generated.js';
+// package.json sits one level above both src/ and dist/.
+const { version } = createRequire(import.meta.url)('../package.json');
+async function request(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof ORPCError)
+            throw error;
+        throw new ORPCError('SERVICE_UNAVAILABLE', {
+            message: 'Could not read a response from Shuffl. Check the current resource or command receipt before retrying a write.',
+        });
+    }
+}
+const stdin = async () => {
+    const chunks = [];
+    let size = 0;
+    for await (const value of process.stdin) {
+        const chunk = Buffer.from(value);
+        size += chunk.length;
+        if (size > 1024 * 1024)
+            throw new Error('Input exceeds 1 MiB.');
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+};
+function parse(args) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const [name, ...value] = arg.slice(2).split('=');
+        if (!name || name in flags)
+            throw new Error(`Duplicate or invalid flag: ${arg}`);
+        if (['help', 'json', 'token-stdin', 'version'].includes(name)) {
+            if (value.length)
+                throw new Error(`--${name} takes no value`);
+            flags[name] = true;
+            continue;
+        }
+        const next = value.length ? value.join('=') : args[++i];
+        if (next === undefined || next.startsWith('--'))
+            throw new Error(`--${name} requires a value`);
+        flags[name] = next;
+    }
+    return { flags, positional };
+}
+function scalar(raw, schema) {
+    if (schema.type === 'integer' || schema.type === 'number') {
+        const value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new Error(`Expected a number, received ${raw}`);
+        return value;
+    }
+    if (schema.type === 'boolean') {
+        if (raw !== 'true' && raw !== 'false')
+            throw new Error('Boolean flags accept true or false.');
+        return raw === 'true';
+    }
+    if (schema.type === 'object' || schema.type === 'array')
+        return JSON.parse(raw);
+    return raw;
+}
+export async function runCli(args, io = {
+    env: process.env,
+    stderr: (s) => process.stderr.write(s),
+    stdin,
+    stdout: (s) => process.stdout.write(s),
+}) {
+    const json = args.includes('--json');
+    try {
+        const { positional, flags } = parse(args);
+        const configFile = join(io.env.SHUFFL_CONFIG_DIR ??
+            join(io.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'shuffl'), 'config.json');
+        if (flags.version && !positional.length) {
+            io.stdout(json ? `${JSON.stringify({ version })}\n` : `${version}\n`);
+            return 0;
+        }
+        if (flags.help || !positional.length) {
+            const definition = commands.find((c) => c.command.join(' ') === positional.join(' '));
+            io.stdout(definition
+                ? `${definition.summary}\nPermission: ${definition.permission} (${definition.access})\n\nshuffl ${definition.command.join(' ')} [--input JSON | --input-file FILE] [--json]\n${Object.entries(definition.input?.properties ?? {})
+                    .map(([key, value]) => `  --${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)} <${value.type ?? 'json'}>`)
+                    .join('\n')}\n`
+                : `Shuffl CLI ${version}\n\n  shuffl login --base-url URL --token-stdin\n  shuffl logout\n  shuffl --version\n${commands.map((c) => `  shuffl ${c.command.join(' ')} — ${c.summary}`).join('\n')}\n\nUse --help on a command for inputs. Use --json for machine-readable output.\nCreate a key in Settings → API keys and choose the endpoint permissions this CLI needs.\n`);
+            return 0;
+        }
+        if (positional.length === 1 && positional[0] === 'logout') {
+            if (Object.keys(flags).some((k) => k !== 'json'))
+                throw new Error('Unknown logout flag.');
+            await rm(configFile, { force: true });
+            io.stdout(json
+                ? '{}\n'
+                : 'Signed out locally. Revoke the token in Settings to disable other copies.\n');
+            return 0;
+        }
+        if (positional.length === 1 && positional[0] === 'login') {
+            if (Object.keys(flags).some((k) => !['base-url', 'token-stdin', 'json'].includes(k)))
+                throw new Error('Unknown login flag.');
+            if (!flags['token-stdin'] || typeof flags['base-url'] !== 'string')
+                throw new Error('Use login --base-url URL --token-stdin. The token is read from standard input.');
+            const token = (await io.stdin()).trim();
+            if (!/^shuffl_api_[A-Za-z0-9_-]{43}$/.test(token))
+                throw new Error('Expected a Shuffl API token.');
+            const baseUrl = new URL(flags['base-url']).origin;
+            const client = createShuffl({
+                baseUrl,
+                token,
+            });
+            const workspace = await request(() => client.workspaces.current());
+            await mkdir(dirname(configFile), { mode: 0o700, recursive: true });
+            const temporary = `${configFile}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify({ baseUrl, token }) + '\n', {
+                    flag: 'wx',
+                    mode: 0o600,
+                });
+                await rename(temporary, configFile);
+                await chmod(configFile, 0o600);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+            io.stdout(json
+                ? JSON.stringify({ workspace }) + '\n'
+                : `Signed in to ${workspace.name}.\n`);
+            return 0;
+        }
+        const command = commands.find((c) => c.command.join(' ') === positional.join(' '));
+        if (!command)
+            throw new Error('Unknown command. Run shuffl --help.');
+        const fields = command.input?.properties ?? {};
+        const names = Object.fromEntries(Object.keys(fields).map((key) => [
+            key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`),
+            key,
+        ]));
+        for (const key of Object.keys(flags))
+            if (!['json', 'input', 'input-file', 'base-url'].includes(key) &&
+                !(key in names))
+                throw new Error(`Unknown flag --${key}.`);
+        if (flags.input && flags['input-file'])
+            throw new Error('Choose --input or --input-file.');
+        let input;
+        if (typeof flags.input === 'string')
+            input = JSON.parse(flags.input === '-' ? await io.stdin() : flags.input);
+        else if (typeof flags['input-file'] === 'string')
+            input = JSON.parse(await readFile(flags['input-file'], 'utf8'));
+        else
+            input = command.input ? {} : undefined;
+        if (input !== undefined &&
+            (typeof input !== 'object' || input === null || Array.isArray(input)))
+            throw new Error('Input must be a JSON object.');
+        for (const [flag, key] of Object.entries(names))
+            if (typeof flags[flag] === 'string') {
+                if (input && Object.hasOwn(input, key))
+                    throw new Error(`Input ${key} was provided more than once.`);
+                input[key] = scalar(flags[flag], fields[key]);
+            }
+        let saved;
+        try {
+            saved = JSON.parse(await readFile(configFile, 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new Error('Cannot read CLI configuration. Run shuffl login again.');
+        }
+        const token = io.env.SHUFFL_TOKEN ?? saved?.token;
+        const baseUrl = typeof flags['base-url'] === 'string'
+            ? flags['base-url']
+            : (io.env.SHUFFL_BASE_URL ?? saved?.baseUrl);
+        if (!token || !baseUrl)
+            throw new Error('Run shuffl login, or set SHUFFL_TOKEN and SHUFFL_BASE_URL.');
+        if (!io.env.SHUFFL_TOKEN &&
+            saved &&
+            new URL(baseUrl).origin !== new URL(saved.baseUrl).origin)
+            throw new Error('Saved credentials belong to a different server. Sign in to the target server first.');
+        let method = createShuffl({ baseUrl, token });
+        for (const name of command.path)
+            method = method[name];
+        const output = await request(() => method(input));
+        io.stdout(JSON.stringify(output, null, json ? undefined : 2) + '\n');
+        return 0;
+    }
+    catch (error) {
+        const code = error instanceof ORPCError ? error.code : 'CLI_ERROR';
+        const message = error instanceof Error ? error.message : 'Command failed.';
+        (json ? io.stdout : io.stderr)(json
+            ? JSON.stringify({ error: { code, message } }) + '\n'
+            : `${message}\n`);
+        return code === 'UNAUTHORIZED' || code === 'FORBIDDEN'
+            ? 3
+            : code === 'CLI_ERROR' || code === 'BAD_REQUEST'
+                ? 2
+                : 1;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export interface JsonSchema {
+    [key: string]: unknown;
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    description?: string;
+}
+export interface CommandDefinition {
+    permission: string;
+    access: 'read' | 'write';
+    path: string[];
+    command: string[];
+    summary: string;
+    scope: string | null;
+    input: JsonSchema | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "dependencies": {
+    "@orpc/client": "1.15.3",
+    "@shuffl/api-contracts": "0.1.0",
+    "@shuffl/sdk": "0.1.0"
+  },
+  "description": "Shuffl command line: every public API operation as a scriptable command with JSON output.",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "homepage": "https://shuffl-rebuild.vercel.app/docs/sdk",
+  "keywords": [
+    "shuffl",
+    "cli",
+    "hr"
+  ],
+  "license": "MIT",
+  "name": "@shuffl/cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.1.0",
+  "bin": {
+    "shuffl": "./dist/bin.js"
+  }
+}