@mdsrs/cli 0.0.0

package/README.md

@@ -0,0 +1,16 @@
+# @mdsrs/cli
+
+Command-line tools for Markdown-native spaced repetition collections.
+
+## Commands
+
+```sh
+mdsrs init ./cards
+mdsrs check ./cards
+mdsrs export ./cards
+mdsrs export ./cards --pretty
+```
+
+`init` creates a starter collection with basic, cloze, math, and nested deck
+examples. `check` loads a collection and prints a short summary. `export` emits
+the parsed collection as JSON for other tools.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+export interface CliIo {
+    stdout: Pick<NodeJS.WriteStream, 'write'>;
+    stderr: Pick<NodeJS.WriteStream, 'write'>;
+}
+export declare const runCli: (argv: string[], io?: CliIo) => Promise<1 | 0>;
+interface InitCollectionOptions {
+    force?: boolean;
+}
+interface InitCollectionResult {
+    rootPath: string;
+    writtenFiles: string[];
+}
+export declare const initCollection: (root: string, options?: InitCollectionOptions) => Promise<InitCollectionResult>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAMA,MAAM,WAAW,KAAK;IACrB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CAC1C;AAcD,eAAO,MAAM,MAAM,GAClB,MAAM,MAAM,EAAE,EACd,KAAI,KAA0D,mBAwC9D,CAAC;AAgCF,UAAU,qBAAqB;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,oBAAoB;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;CACvB;AAoDD,eAAO,MAAM,cAAc,GAC1B,MAAM,MAAM,EACZ,UAAS,qBAA0B,KACjC,OAAO,CAAC,oBAAoB,CAqB9B,CAAC"}

package/dist/index.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadCollection } from '@mdsrs/fs';
+const usage = `Usage:
+  mdsrs init <root> [--force]
+  mdsrs check <root>
+  mdsrs export <root> [--pretty]
+  mdsrs help
+`;
+export const runCli = async (argv, io = { stdout: process.stdout, stderr: process.stderr }) => {
+    const [command, ...args] = argv;
+    try {
+        if (!command || command === 'help' || command === '--help' || command === '-h') {
+            io.stdout.write(usage);
+            return 0;
+        }
+        if (command === 'init') {
+            const { root, options } = parseRootCommand(args);
+            rejectUnusedOptions(options, ['pretty']);
+            const result = await initCollection(root, { force: options.force });
+            io.stdout.write(formatInitSummary(result));
+            return 0;
+        }
+        if (command === 'check') {
+            const { root, options } = parseRootCommand(args);
+            rejectUnusedOptions(options, ['force', 'pretty']);
+            const collection = await loadCollection(root);
+            io.stdout.write(formatSummary(collection));
+            return 0;
+        }
+        if (command === 'export') {
+            const { root, options } = parseRootCommand(args);
+            rejectUnusedOptions(options, ['force']);
+            const collection = await loadCollection(root);
+            io.stdout.write(`${JSON.stringify(collection, null, options.pretty ? 2 : 0)}\n`);
+            return 0;
+        }
+        io.stderr.write(`Unknown command: ${command}\n\n${usage}`);
+        return 1;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+};
+const parseRootCommand = (args) => {
+    const options = { force: false, pretty: false };
+    const positionals = [];
+    for (const arg of args) {
+        if (arg === '--force')
+            options.force = true;
+        else if (arg === '--pretty')
+            options.pretty = true;
+        else if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    const [root, extra] = positionals;
+    if (!root)
+        throw new Error(`Missing collection root.\n\n${usage}`);
+    if (extra)
+        throw new Error(`Unexpected argument: ${extra}`);
+    return {
+        root,
+        options
+    };
+};
+const rejectUnusedOptions = (options, unusedOptions) => {
+    for (const option of unusedOptions) {
+        if (options[option])
+            throw new Error(`Option is not supported for this command: --${option}`);
+    }
+};
+const starterFiles = {
+    'README.md': `# mdsrs cards
+
+This folder is a Markdown-native spaced repetition collection.
+
+Run:
+
+\`\`\`sh
+mdsrs check .
+mdsrs export . --pretty
+\`\`\`
+
+Cards live in Markdown files. Use \`Q:\` and \`A:\` for basic cards, or \`C:\`
+with bracketed text for cloze cards.
+`,
+    'cards/index.md': `---
+name = "Cards"
+---
+
+Q: What is the source of truth in mdsrs?
+A: Markdown files.
+
+---
+
+C: Editing card [content] changes its deterministic hash.
+`,
+    'cards/example/math.md': `---
+name = "Math"
+---
+
+Q: What is the derivative of $x^2$?
+A: $2x$.
+
+---
+
+C: Euler's identity is $e^{i\\pi} + [1] = 0$.
+`,
+    'cards/example/concepts.md': `---
+name = "Concepts"
+---
+
+Q: What does a card hash identify?
+A: The normalized card content, not a database row.
+
+---
+
+C: Nested folders become nested [decks].
+`
+};
+export const initCollection = async (root, options = {}) => {
+    const rootPath = path.resolve(root);
+    await mkdir(rootPath, { recursive: true });
+    const entries = await readdir(rootPath);
+    if (!options.force && entries.length > 0) {
+        throw new Error(`Refusing to initialize non-empty directory without --force: ${rootPath}`);
+    }
+    const writtenFiles = [];
+    for (const [relativePath, content] of Object.entries(starterFiles)) {
+        const absolutePath = path.join(rootPath, ...relativePath.split('/'));
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, content, 'utf8');
+        writtenFiles.push(relativePath);
+    }
+    return {
+        rootPath,
+        writtenFiles
+    };
+};
+const countDeckNodes = (nodes) => nodes.reduce((total, node) => total + 1 + countDeckNodes(node.children), 0);
+const formatSummary = (collection) => [
+    `root: ${collection.rootPath}`,
+    `sources: ${collection.sources.length}`,
+    `cards: ${collection.cards.length}`,
+    `decks: ${countDeckNodes(collection.deckTree)}`,
+    `assets: ${collection.assets.length}`
+].join('\n') + '\n';
+const formatInitSummary = (result) => [
+    `initialized: ${result.rootPath}`,
+    `files: ${result.writtenFiles.length}`,
+    ...result.writtenFiles.map((filePath) => `created: ${filePath}`)
+].join('\n') + '\n';
+const isMain = () => {
+    const entrypoint = process.argv[1];
+    return entrypoint ? path.resolve(entrypoint) === fileURLToPath(import.meta.url) : false;
+};
+if (isMain()) {
+    process.exitCode = await runCli(process.argv.slice(2));
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@mdsrs/cli",
+  "version": "0.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "mdsrs": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@mdsrs/fs": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}