@convex-localfirst/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fanzzzd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @convex-localfirst/cli
+
+Command-line tooling for convex-localfirst:
+
+- **`codegen`** — derive the client manifest from your `lf.table` DSL.
+- **`check`** — statically catch direct `ctx.db.insert/replace` writes to local-first
+  tables (a security guard; these must go through the generated wrappers).
+- **`dev`** — run the codegen + check pipeline.
+
+```bash
+npm install -D @convex-localfirst/cli
+# run under a TS loader so it can read your TypeScript Convex modules:
+node --import tsx node_modules/@convex-localfirst/cli/dist/index.js codegen
+```
+
+Peer dependency: `typescript`. MIT

package/dist/check.d.ts

@@ -0,0 +1,22 @@
+export type SourceFile = {
+    readonly path: string;
+    readonly content: string;
+};
+export type Violation = {
+    readonly file: string;
+    readonly line: number;
+    readonly table: string;
+    readonly method: string;
+    readonly snippet: string;
+};
+/** Collect table names declared local-first via the DSL (`lf.table("name", ...)`). */
+export declare function collectLocalFirstTables(files: readonly SourceFile[]): string[];
+/**
+ * Detect direct `ctx.db.insert("<lfTable>", …)` calls — writes that bypass the
+ * local-first wrappers and the sync ledger (Security: I10).
+ */
+export declare function findDirectWrites(files: readonly SourceFile[], lfTables: readonly string[]): Violation[];
+export declare function findIdBasedWrites(files: readonly SourceFile[], lfTables: readonly string[]): Violation[];
+export declare function readSourceFiles(dir: string): SourceFile[];
+/** Run the full check over a directory. Returns violations (empty = clean). */
+export declare function runCheck(dir: string): Violation[];

package/dist/check.js

@@ -0,0 +1,293 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import * as ts from "typescript";
+const TABLE_DECL = /\.table\s*\(\s*["'`]([^"'`]+)["'`]/g;
+// High-confidence direct write: ctx.db.insert("<table>", …). `insert` is the only
+// db write that names the table as a string literal; patch/delete/replace take a
+// document id (covered by the AST pass below). Tolerates whitespace/newlines.
+const DIRECT_INSERT = /ctx\s*\.\s*db\s*\.\s*(insert)\s*\(\s*["'`]([^"'`]+)["'`]/g;
+/** Collect table names declared local-first via the DSL (`lf.table("name", ...)`). */
+export function collectLocalFirstTables(files) {
+    const tables = new Set();
+    for (const file of files) {
+        for (const match of file.content.matchAll(TABLE_DECL)) {
+            tables.add(match[1]);
+        }
+    }
+    return [...tables];
+}
+function lineOf(content, index) {
+    return content.slice(0, index).split("\n").length;
+}
+/**
+ * Detect direct `ctx.db.insert("<lfTable>", …)` calls — writes that bypass the
+ * local-first wrappers and the sync ledger (Security: I10).
+ */
+export function findDirectWrites(files, lfTables) {
+    const violations = [];
+    const lfSet = new Set(lfTables);
+    for (const file of files) {
+        for (const match of file.content.matchAll(DIRECT_INSERT)) {
+            const [, method, table] = match;
+            if (lfSet.has(table)) {
+                const line = lineOf(file.content, match.index ?? 0);
+                violations.push({
+                    file: file.path,
+                    line,
+                    table,
+                    method,
+                    snippet: file.content.split("\n")[line - 1]?.trim() ?? ""
+                });
+            }
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// AST pass: id-based writes (ctx.db.patch/delete/replace) to local-first rows.
+//
+// patch/delete/replace take a document id, not a table literal, so they can't be
+// matched by regex. This pass tracks, *within a single function*, ids that
+// provably come from a local-first table and flags writes that use them. It is
+// SOUND by construction — it only flags when it can see the id's origin, so a
+// clean result over recognized patterns is real (no false positives). It does
+// NOT trace ids across function boundaries or through ctx.db.get(); those stay
+// unflagged (false negatives), same coverage class as before but strictly more.
+//
+// ponytail: syntactic, function-scoped taint over `const`/handler-args only —
+// no type checker, no cross-call dataflow. Upgrade path: a full ts.Program +
+// TypeChecker pass if cross-function id passing shows up as a real miss.
+// ---------------------------------------------------------------------------
+const ID_WRITE_METHODS = new Set(["patch", "delete", "replace"]);
+function freshScope() {
+    return { constDoc: new Map(), argTaint: new Map(), destructuredIds: new Map() };
+}
+function unwrap(node) {
+    if (ts.isAwaitExpression(node) || ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node)) {
+        return unwrap(node.expression);
+    }
+    return node;
+}
+/** `ctx.db.<method>`? Returns the method name. Hardcodes the `ctx.db` convention. */
+function ctxDbMethod(callee) {
+    if (!ts.isPropertyAccessExpression(callee))
+        return undefined;
+    const obj = callee.expression;
+    if (ts.isPropertyAccessExpression(obj) &&
+        obj.name.text === "db" &&
+        ts.isIdentifier(obj.expression) &&
+        obj.expression.text === "ctx") {
+        return callee.name.text;
+    }
+    return undefined;
+}
+/** Walk a query chain down to `ctx.db.query("X")`; return X if it is an lf table. */
+function queryRootTable(expr, lfSet) {
+    let cur = expr;
+    for (;;) {
+        if (ts.isCallExpression(cur)) {
+            const callee = cur.expression;
+            if (ts.isPropertyAccessExpression(callee) && ctxDbMethod(callee) === "query") {
+                const arg = cur.arguments[0];
+                if (arg && ts.isStringLiteralLike(arg) && lfSet.has(arg.text))
+                    return arg.text;
+                return undefined;
+            }
+            cur = callee;
+        }
+        else if (ts.isPropertyAccessExpression(cur) || ts.isElementAccessExpression(cur)) {
+            cur = cur.expression;
+        }
+        else if (ts.isNonNullExpression(cur) || ts.isParenthesizedExpression(cur)) {
+            cur = cur.expression;
+        }
+        else {
+            return undefined;
+        }
+    }
+}
+/** A single-doc query (`…first()`/`…unique()`) rooted at an lf table -> the table. */
+function singleDocQueryTable(expr, lfSet) {
+    const e = unwrap(expr);
+    if (!ts.isCallExpression(e))
+        return undefined;
+    const callee = e.expression;
+    if (!ts.isPropertyAccessExpression(callee))
+        return undefined;
+    if (callee.name.text !== "first" && callee.name.text !== "unique")
+        return undefined;
+    return queryRootTable(callee.expression, lfSet);
+}
+/** Classify the id argument of a patch/delete/replace call -> lf table, or undefined. */
+function classifyId(arg, scope, lfSet) {
+    const a = unwrap(arg);
+    if (ts.isPropertyAccessExpression(a)) {
+        const base = a.expression;
+        if (a.name.text === "_id") {
+            // <constDoc>._id  or  (await ctx.db.query("lf")…first())._id
+            if (ts.isIdentifier(base) && scope.constDoc.has(base.text))
+                return scope.constDoc.get(base.text);
+            const inline = singleDocQueryTable(base, lfSet);
+            if (inline)
+                return inline;
+        }
+        else if (ts.isIdentifier(base) && base.text === scope.argParam) {
+            // args.<field> where field is a v.id("lf") validator
+            return scope.argTaint.get(a.name.text);
+        }
+    }
+    else if (ts.isIdentifier(a)) {
+        // handler destructured `({ id })` where id is a v.id("lf") validator
+        return scope.destructuredIds.get(a.text);
+    }
+    return undefined;
+}
+/** Extract field -> lf table from an `args: { f: v.id("lf") }` validator object. */
+function readArgValidators(argsValue, lfSet, out) {
+    if (!ts.isObjectLiteralExpression(argsValue))
+        return;
+    for (const prop of argsValue.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const name = prop.name;
+        if (!ts.isIdentifier(name) && !ts.isStringLiteral(name))
+            continue;
+        const field = name.text;
+        const call = prop.initializer;
+        // v.id("lf")  — PropertyAccess `.id` called with a single string literal.
+        if (ts.isCallExpression(call) &&
+            ts.isPropertyAccessExpression(call.expression) &&
+            call.expression.name.text === "id") {
+            const tbl = call.arguments[0];
+            if (tbl && ts.isStringLiteralLike(tbl) && lfSet.has(tbl.text))
+                out.set(field, tbl.text);
+        }
+    }
+}
+function scriptKindFor(path) {
+    if (path.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (path.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    if (path.endsWith(".js"))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+export function findIdBasedWrites(files, lfTables) {
+    const lfSet = new Set(lfTables);
+    if (lfSet.size === 0)
+        return [];
+    const violations = [];
+    for (const file of files) {
+        const sf = ts.createSourceFile(file.path, file.content, ts.ScriptTarget.Latest, 
+        /* setParentNodes */ true, scriptKindFor(file.path));
+        const record = (node, table, method) => {
+            const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+            violations.push({
+                file: file.path,
+                line,
+                table,
+                method,
+                snippet: file.content.split("\n")[line - 1]?.trim() ?? ""
+            });
+        };
+        const visit = (node, scope) => {
+            // Convex function definition shape: someWrapper({ args?, handler }).
+            if (ts.isCallExpression(node) && node.arguments.length === 1) {
+                const arg0 = node.arguments[0];
+                if (ts.isObjectLiteralExpression(arg0)) {
+                    const handlerProp = arg0.properties.find((p) => ts.isPropertyAssignment(p) &&
+                        ts.isIdentifier(p.name) &&
+                        p.name.text === "handler" &&
+                        (ts.isArrowFunction(p.initializer) || ts.isFunctionExpression(p.initializer)));
+                    if (handlerProp) {
+                        const handlerScope = freshScope();
+                        const argsProp = arg0.properties.find((p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "args");
+                        if (argsProp)
+                            readArgValidators(argsProp.initializer, lfSet, handlerScope.argTaint);
+                        const handler = handlerProp.initializer;
+                        const argsParam = handler.parameters[1];
+                        if (argsParam) {
+                            if (ts.isIdentifier(argsParam.name)) {
+                                handlerScope.argParam = argsParam.name.text;
+                            }
+                            else if (ts.isObjectBindingPattern(argsParam.name)) {
+                                for (const el of argsParam.name.elements) {
+                                    if (!ts.isIdentifier(el.name))
+                                        continue;
+                                    const field = el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text : el.name.text;
+                                    const tbl = handlerScope.argTaint.get(field);
+                                    if (tbl)
+                                        handlerScope.destructuredIds.set(el.name.text, tbl);
+                                }
+                            }
+                        }
+                        // Visit the handler body in its own scope; visit the rest (incl. the
+                        // args validators) in the outer scope.
+                        if (handler.body)
+                            visit(handler.body, handlerScope);
+                        for (const prop of arg0.properties) {
+                            if (prop !== handlerProp)
+                                visit(prop, scope);
+                        }
+                        return;
+                    }
+                }
+            }
+            // `const x = await ctx.db.query("lf")…first()/.unique()` taints x as a doc.
+            if (ts.isVariableStatement(node) && (node.declarationList.flags & ts.NodeFlags.Const) !== 0) {
+                for (const decl of node.declarationList.declarations) {
+                    if (ts.isIdentifier(decl.name) && decl.initializer) {
+                        const tbl = singleDocQueryTable(decl.initializer, lfSet);
+                        if (tbl)
+                            scope.constDoc.set(decl.name.text, tbl);
+                    }
+                }
+            }
+            // ctx.db.patch/delete/replace(<id>, …)
+            if (ts.isCallExpression(node)) {
+                const method = ctxDbMethod(node.expression);
+                if (method && ID_WRITE_METHODS.has(method) && node.arguments[0]) {
+                    const tbl = classifyId(node.arguments[0], scope, lfSet);
+                    if (tbl)
+                        record(node, tbl, method);
+                }
+            }
+            node.forEachChild((child) => visit(child, scope));
+        };
+        visit(sf, freshScope());
+    }
+    return violations;
+}
+export function readSourceFiles(dir) {
+    const files = [];
+    const walk = (current) => {
+        let entries;
+        try {
+            entries = readdirSync(current);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === "node_modules" || entry === "_generated" || entry === "dist") {
+                continue;
+            }
+            const full = join(current, entry);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else if (/\.(ts|tsx|js|jsx)$/.test(entry)) {
+                files.push({ path: full, content: readFileSync(full, "utf8") });
+            }
+        }
+    };
+    walk(dir);
+    return files;
+}
+/** Run the full check over a directory. Returns violations (empty = clean). */
+export function runCheck(dir) {
+    const files = readSourceFiles(dir);
+    const lfTables = collectLocalFirstTables(files);
+    return [...findDirectWrites(files, lfTables), ...findIdBasedWrites(files, lfTables)];
+}

package/dist/codegen.d.ts

@@ -0,0 +1,44 @@
+import type { DeclarativeInsert, DeclarativePatch, DeclarativeQuery, DeclarativeRemove } from "@convex-localfirst/core/internal";
+type Scope = {
+    kind: "byUser";
+    field: string;
+} | {
+    kind: "byWorkspace";
+    workspaceIdField: string;
+    membershipTable: string;
+} | {
+    kind: "byProject";
+    projectIdField: string;
+    membershipTable: string;
+};
+export type TableMeta = {
+    table: string;
+    idField: string;
+    conflict: string;
+    scope: Scope;
+    indexes: Record<string, readonly string[]>;
+    setFields?: readonly string[];
+    counterFields?: readonly string[];
+};
+export type ManifestEntry = {
+    type: "query";
+    tableMeta: TableMeta;
+    descriptor: DeclarativeQuery;
+} | {
+    type: "insert";
+    tableMeta: TableMeta;
+    descriptor: DeclarativeInsert;
+} | {
+    type: "patch";
+    tableMeta: TableMeta;
+    descriptor: DeclarativePatch;
+} | {
+    type: "remove";
+    tableMeta: TableMeta;
+    descriptor: DeclarativeRemove;
+};
+/** Introspect one module's exports into manifest entries. Names become "moduleName:exportName". */
+export declare function introspectExports(moduleName: string, exports: Record<string, unknown>): ManifestEntry[];
+/** Emit a browser-safe manifest module (pure data + generic interpreters). */
+export declare function emitManifestSource(schemaVersion: number, entries: readonly ManifestEntry[]): string;
+export {};

package/dist/codegen.js

@@ -0,0 +1,291 @@
+// --- Source-based introspection (parses the closure with fn.toString) ---------
+// We read how each output field is built rather than executing the closure, so
+// wrappers like String()/Boolean()/Number() are handled and nothing is guessed.
+/** Split top-level segments of `body` on `delim`, respecting (), {}, [] and quotes. */
+function splitTopLevel(body, delim) {
+    const out = [];
+    let depth = 0;
+    let quote = null;
+    let current = "";
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (quote) {
+            current += ch;
+            if (ch === quote && body[i - 1] !== "\\")
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === "`") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === "(" || ch === "{" || ch === "[")
+            depth++;
+        if (ch === ")" || ch === "}" || ch === "]")
+            depth--;
+        if (depth === 0 && ch === delim) {
+            out.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        out.push(current);
+    return out;
+}
+/** Extract the returned object-literal body (the text between the outer braces). */
+function returnedObjectBody(fnSource, fnName) {
+    const arrow = fnSource.indexOf("=>");
+    let body = arrow >= 0 ? fnSource.slice(arrow + 2).trim() : fnSource;
+    if (body.startsWith("("))
+        body = body.slice(1, body.lastIndexOf(")")).trim();
+    if (body.startsWith("{") && !body.includes("return")) {
+        return body.slice(1, body.lastIndexOf("}"));
+    }
+    // Block body: take the expression after `return`.
+    const ret = body.indexOf("return");
+    if (ret >= 0) {
+        let expr = body.slice(ret + 6).trim();
+        if (expr.endsWith(";"))
+            expr = expr.slice(0, -1).trim();
+        if (expr.startsWith("("))
+            expr = expr.slice(1, expr.lastIndexOf(")")).trim();
+        if (expr.startsWith("{"))
+            return expr.slice(1, expr.lastIndexOf("}"));
+    }
+    throw new Error(`codegen: cannot parse the object returned by "${fnName}".`);
+}
+/** Classify a single value expression into a FieldSource. */
+function classifyExpr(raw, fnName, field) {
+    let expr = raw.trim();
+    const wrap = /^(?:String|Number|Boolean)\((.*)\)$/.exec(expr);
+    if (wrap)
+        expr = wrap[1].trim();
+    const argDot = /^args\.([A-Za-z_$][\w$]*)$/.exec(expr);
+    if (argDot)
+        return { from: "arg", arg: argDot[1] };
+    const argIdx = /^args\[\s*['"]([^'"]+)['"]\s*\]$/.exec(expr);
+    if (argIdx)
+        return { from: "arg", arg: argIdx[1] };
+    if (/^auth\.userId$/.test(expr))
+        return { from: "auth" };
+    if (/^now$/.test(expr))
+        return { from: "now" };
+    if (expr === "true")
+        return { from: "const", value: true };
+    if (expr === "false")
+        return { from: "const", value: false };
+    if (expr === "null")
+        return { from: "const", value: null };
+    if (/^-?\d+(\.\d+)?$/.test(expr))
+        return { from: "const", value: Number(expr) };
+    const str = /^['"](.*)['"]$/.exec(expr);
+    if (str)
+        return { from: "const", value: str[1] };
+    throw new Error(`codegen: field "${field}" in "${fnName}" uses an unsupported expression \`${raw.trim()}\` — use a literal, args.x, auth.userId, or now.`);
+}
+function parseFields(fnSource, fnName) {
+    const body = returnedObjectBody(fnSource, fnName);
+    const fields = {};
+    for (const pair of splitTopLevel(body, ",")) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue; // trailing comma / empty segment
+        const colon = trimmed.indexOf(":");
+        if (colon < 0) {
+            // Shorthand ({ x }), spread ({ ...args }), or a method can't be statically
+            // mapped to a FieldSource. FAIL CLOSED — silently skipping would emit a manifest
+            // missing fields, which then pushes wrong/empty values to the server.
+            throw new Error(`codegen: field segment \`${trimmed}\` in "${fnName}" is not a "key: expr" pair. ` +
+                `Shorthand, spread (...), and methods are unsupported — write explicit "field: args.x" entries.`);
+        }
+        const rawKey = trimmed.slice(0, colon).trim();
+        if (rawKey.startsWith("[") || rawKey.includes("(")) {
+            throw new Error(`codegen: computed/method key \`${rawKey}\` in "${fnName}" is unsupported — use a static field name.`);
+        }
+        const key = rawKey.replace(/^['"]|['"]$/g, "");
+        fields[key] = classifyExpr(trimmed.slice(colon + 1), fnName, key);
+    }
+    return fields;
+}
+function idArgOf(idFn, fnName) {
+    const source = String(idFn);
+    const arrow = source.indexOf("=>");
+    let expr = arrow >= 0 ? source.slice(arrow + 2).trim() : source;
+    if (expr.endsWith(";"))
+        expr = expr.slice(0, -1).trim();
+    const wrap = /^(?:String|Number)\((.*)\)$/.exec(expr);
+    if (wrap)
+        expr = wrap[1].trim();
+    const m = /^args\.([A-Za-z_$][\w$]*)$/.exec(expr) ?? /^args\[\s*['"]([^'"]+)['"]\s*\]$/.exec(expr);
+    if (m)
+        return m[1];
+    throw new Error(`codegen: cannot determine the id arg for "${fnName}" (id() must return args.<field>).`);
+}
+/** The id arg from an explicit `id()` closure, or — when omitted — by convention: the arg
+ *  named "id" (the dominant REST-y convention; note the id ARG and the row idField are
+ *  different axes), else the arg named after the table's idField. FAILS CLOSED if neither
+ *  exists: defaulting to a non-existent arg would emit a descriptor whose patch/remove has
+ *  no id at runtime, so demand an explicit id(). */
+function idArgOrDefault(spec, idField, fnName) {
+    if (spec.id)
+        return idArgOf(spec.id, fnName);
+    const argKeys = Object.keys(spec.args ?? {});
+    if (argKeys.includes("id"))
+        return "id";
+    if (argKeys.includes(idField))
+        return idField;
+    throw new Error(`codegen: "${fnName}" omits id() but has neither an "id" arg nor one named "${idField}" (the table's idField). ` +
+        `Add id: ({ args }) => args.<field>.`);
+}
+/** Default patch when `patch()` is omitted: forward every declared arg 1:1 (field === arg
+ *  name) EXCEPT the id arg (you never patch the id). This is the common "update these
+ *  fields" case; a table that also sets computed fields (e.g. updated_at: now) writes an
+ *  explicit patch() instead. */
+function defaultPatchFields(spec, idArg) {
+    const fields = {};
+    for (const key of Object.keys(spec.args ?? {})) {
+        if (key === idArg)
+            continue;
+        fields[key] = { from: "arg", arg: key };
+    }
+    return fields;
+}
+function scopeField(scope) {
+    if (scope.kind === "byUser")
+        return scope.field;
+    if (scope.kind === "byWorkspace")
+        return scope.workspaceIdField;
+    if (scope.kind === "byProject")
+        return scope.projectIdField;
+    return undefined;
+}
+function tableMetaOf(meta) {
+    return {
+        table: meta.tableName,
+        idField: meta.idField,
+        conflict: meta.conflict,
+        scope: meta.scope,
+        indexes: meta.indexes,
+        setFields: meta.setFields,
+        counterFields: meta.counterFields
+    };
+}
+/** Introspect one module's exports into manifest entries. Names become "moduleName:exportName". */
+export function introspectExports(moduleName, exports) {
+    const entries = [];
+    for (const [exportName, value] of Object.entries(exports)) {
+        const meta = value?.__convexLocalFirst;
+        if (!meta)
+            continue;
+        const name = `${moduleName}:${exportName}`;
+        const tableMeta = tableMetaOf(meta);
+        const spec = meta.spec;
+        if (meta.kind === "query") {
+            const argKeys = Object.keys(spec.args ?? {});
+            const indexCols = (meta.indexes[String(spec.index)] ?? []);
+            const sortField = indexCols.find((c) => c !== scopeField(meta.scope) && !argKeys.includes(c));
+            entries.push({
+                type: "query",
+                tableMeta,
+                descriptor: {
+                    name,
+                    table: meta.tableName,
+                    filters: argKeys,
+                    orderBy: sortField,
+                    order: spec.order ?? "asc",
+                    initial: spec.initial,
+                    // Workspace/project queries carry their pull scope (value comes from the
+                    // arg named after the scope field). byUser is derived by the engine.
+                    scope: meta.scope.kind === "byWorkspace"
+                        ? { kind: "byWorkspace", valueArg: meta.scope.workspaceIdField }
+                        : meta.scope.kind === "byProject"
+                            ? { kind: "byProject", valueArg: meta.scope.projectIdField }
+                            : undefined
+                }
+            });
+        }
+        else if (meta.kind === "insert") {
+            entries.push({
+                type: "insert",
+                tableMeta,
+                descriptor: { name, table: meta.tableName, fields: parseFields(String(spec.value), name) }
+            });
+        }
+        else if (meta.kind === "patch") {
+            const idArg = idArgOrDefault(spec, meta.idField, name);
+            entries.push({
+                type: "patch",
+                tableMeta,
+                descriptor: {
+                    name,
+                    table: meta.tableName,
+                    idArg,
+                    fields: spec.patch ? parseFields(String(spec.patch), name) : defaultPatchFields(spec, idArg)
+                }
+            });
+        }
+        else if (meta.kind === "remove") {
+            entries.push({
+                type: "remove",
+                tableMeta,
+                descriptor: { name, table: meta.tableName, idArg: idArgOrDefault(spec, meta.idField, name) }
+            });
+        }
+    }
+    return entries;
+}
+const BUILDER = {
+    query: "declarativeQuery",
+    insert: "declarativeInsert",
+    patch: "declarativePatch",
+    remove: "declarativeRemove"
+};
+/** Emit a browser-safe manifest module (pure data + generic interpreters). */
+export function emitManifestSource(schemaVersion, entries) {
+    const tables = new Map();
+    for (const entry of entries)
+        tables.set(entry.tableMeta.table, entry.tableMeta);
+    const tableLines = [...tables.values()].map((t) => `    ${JSON.stringify(t.table)}: localTable(${JSON.stringify({
+        table: t.table,
+        idField: t.idField,
+        scope: t.scope,
+        conflict: t.conflict,
+        indexes: t.indexes,
+        // Only emitted when declared, so tables without set/counter fields stay byte-identical.
+        ...(t.setFields && t.setFields.length ? { setFields: t.setFields } : {}),
+        ...(t.counterFields && t.counterFields.length ? { counterFields: t.counterFields } : {})
+    })})`);
+    const queryLines = entries
+        .filter((e) => e.type === "query")
+        .map((e) => `    ${JSON.stringify(e.descriptor.name)}: declarativeQuery(${JSON.stringify(e.descriptor)})`);
+    const mutationLines = entries
+        .filter((e) => e.type !== "query")
+        .map((e) => `    ${JSON.stringify(e.descriptor.name)}: ${BUILDER[e.type]}(${JSON.stringify(e.descriptor)})`);
+    return `// GENERATED by convex-localfirst codegen. Do not edit by hand.
+import { defineLocalFirstManifest, localTable } from "@convex-localfirst/core";
+// Manifest interpreters are internal (I13 / GOAL §6 "no manifest interpreters" in the
+// public surface); generated code is a legitimate internal consumer of them.
+import {
+  declarativeInsert,
+  declarativePatch,
+  declarativeQuery,
+  declarativeRemove
+} from "@convex-localfirst/core/internal";
+
+export const localFirstManifest = defineLocalFirstManifest({
+  schemaVersion: ${schemaVersion},
+  tables: {
+${tableLines.join(",\n")}
+  },
+  queries: {
+${queryLines.join(",\n")}
+  },
+  mutations: {
+${mutationLines.join(",\n")}
+  }
+});
+`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { runCheck } from "./check.js";
+import { emitManifestSource, introspectExports } from "./codegen.js";
+const command = process.argv[2] ?? "help";
+if (command === "init") {
+    init();
+}
+else if (command === "codegen") {
+    await codegen();
+}
+else if (command === "check") {
+    check();
+}
+else if (command === "dev") {
+    await dev();
+}
+else {
+    help();
+}
+function init() {
+    mkdirSync("convex", { recursive: true });
+    mkdirSync("src", { recursive: true });
+    // A COMPLETE, compiling, working starter: schema + factory + component mount +
+    // server sync surface + one example table. Running `init` then `codegen` then
+    // `npx convex dev` gives a live local-first backend with no hand-written sync.
+    // Every file is write-if-absent, so re-running init never clobbers your edits.
+    const files = [
+        {
+            path: join("convex", "schema.ts"),
+            content: `import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+// Your app's own tables. ALL local-first sync bookkeeping (ledger / change log /
+// id map / cursors / tombstones) lives in the mounted @convex-localfirst/component,
+// so your schema only declares domain tables. Each local-first table needs a
+// "localId" field + a "by_localId" index; scope indexes power the per-scope pull.
+export default defineSchema({
+  todos: defineTable({
+    localId: v.string(),
+    ownerId: v.string(),
+    text: v.string(),
+    done: v.boolean(),
+    createdAt: v.number(),
+    updatedAt: v.number()
+  })
+    .index("by_localId", ["localId"])
+    .index("byOwner", ["ownerId", "createdAt"])
+});
+`
+        },
+        {
+            path: join("convex", "localfirst.ts"),
+            content: `import { createLocalFirst } from "@convex-localfirst/server";
+import schema from "./schema";
+
+// Auth is resolved server-side at sync time (convex/sync.ts → createSyncFunctions),
+// not here — this factory only declares the local-first tables.
+export const lf = createLocalFirst({
+  schema,
+  defaults: { idField: "localId", conflict: "fieldLww" }
+});
+`
+        },
+        {
+            path: join("convex", "convex.config.ts"),
+            content: `import { defineApp } from "convex/server";
+import localfirst from "@convex-localfirst/component/convex.config.js";
+
+// Mount the local-first component — the whole "no hand-written backend" promise:
+// the sync ledger / change log / id map / cursors / tombstones come as a drop-in,
+// referenced via components.convexLocalFirst.* in convex/sync.ts.
+const app = defineApp();
+app.use(localfirst);
+
+export default app;
+`
+        },
+        {
+            path: join("convex", "sync.ts"),
+            content: `import { createSyncFunctions } from "@convex-localfirst/server";
+import { components } from "./_generated/api";
+import { mutation, query } from "./_generated/server";
+
+// The entire server sync surface: declare which app tables are local-first + how
+// they're scoped. createSyncFunctions wires app rows to ctx.db and all sync
+// bookkeeping to the mounted component. Add a table here AND in convex/<table>.ts.
+export const { push, pull } = createSyncFunctions({
+  component: components.convexLocalFirst,
+  mutation,
+  query,
+  tables: {
+    todos: { scope: { kind: "byUser" as const, field: "ownerId" }, idField: "localId", conflict: "fieldLww" as const }
+  },
+  // Local dev with no auth provider trusts the client-supplied userId. In
+  // production, DELETE this line and resolve identity from ctx.auth instead.
+  devUnsafeAllowClientUserId: true
+});
+`
+        },
+        {
+            path: join("convex", "todos.ts"),
+            content: `import { v } from "convex/values";
+import { lf } from "./localfirst";
+
+// One local-first table. query/insert/patch/remove run OPTIMISTICALLY on the client
+// and sync via convex/sync.ts — never call these handlers server-side.
+const todos = lf.table("todos", {
+  scope: lf.byUser("ownerId"),
+  indexes: { byOwner: ["ownerId", "createdAt"] }
+});
+
+export const list = todos.query({
+  args: {},
+  index: "byOwner",
+  key: ({ auth }) => [auth.userId],
+  order: "asc",
+  initial: []
+});
+
+export const create = todos.insert({
+  args: { text: v.string() },
+  value: ({ auth, args, now }) => ({
+    ownerId: auth.userId,
+    text: String(args.text),
+    done: false,
+    createdAt: now,
+    updatedAt: now
+  })
+});
+
+// id() defaults to the "id" arg; patch() is explicit only because it computes updatedAt.
+export const toggle = todos.patch({
+  args: { id: v.string(), done: v.boolean() },
+  patch: ({ args, now }) => ({ done: Boolean(args.done), updatedAt: now })
+});
+
+// No id() / patch() needed — remove defaults to the "id" arg.
+export const remove = todos.remove({ args: { id: v.string() } });
+`
+        }
+    ];
+    const created = [];
+    const skipped = [];
+    for (const { path, content } of files) {
+        if (existsSync(path)) {
+            skipped.push(path);
+            continue;
+        }
+        writeFileSync(path, content);
+        created.push(path);
+    }
+    console.log("convex-localfirst init: scaffolded a complete local-first starter.");
+    if (created.length)
+        console.log(`  created: ${created.join(", ")}`);
+    if (skipped.length)
+        console.log(`  kept (already existed): ${skipped.join(", ")}`);
+    console.log(`
+Next:
+  1. npx convex-localfirst codegen   # generate src/convex-localfirst/generated.ts from the DSL
+  2. npx convex dev                  # run the backend + live sync
+  3. Wire the React client: <ConvexProvider client={convex} localFirst={{ manifest, transport, store }}>
+     then useLiveQuery / useMutation (see the README "React hooks" section).`);
+}
+async function codegen() {
+    const convexDir = existsSync("convex") ? "convex" : ".";
+    const skip = new Set(["localfirst.ts", "schema.ts", "convex.config.ts"]);
+    const moduleFiles = readdirSync(convexDir).filter((f) => /\.(ts|js)$/.test(f) && !f.endsWith(".d.ts") && !skip.has(f));
+    const entries = [];
+    const schemaVersion = 1;
+    for (const file of moduleFiles) {
+        const moduleName = file.replace(/\.(ts|js)$/, "");
+        try {
+            const mod = await import(pathToFileURL(resolve(convexDir, file)).href);
+            entries.push(...introspectExports(moduleName, mod));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/Unknown file extension|ERR_UNKNOWN_FILE_EXTENSION/.test(message)) {
+                console.error(`convex-localfirst codegen: cannot import ${file} as raw TypeScript. Run codegen under a TS loader, e.g.\n  node --import tsx node_modules/@convex-localfirst/cli/dist/index.js codegen`);
+                process.exitCode = 1;
+                return;
+            }
+            // A module that can't be imported standalone (e.g. it imports ./_generated
+            // or a mounted component — Convex-runtime-only) is not a local-first table
+            // module, so skip it rather than failing the whole codegen run.
+            console.warn(`convex-localfirst codegen: skipped ${file} (not importable standalone: ${message.split("\n")[0]})`);
+        }
+    }
+    if (entries.length === 0) {
+        console.error("convex-localfirst codegen: found no local-first functions. Define tables with `lf.table(...).query/insert/patch/remove`.");
+        process.exitCode = 1;
+        return;
+    }
+    const outDir = join("src", "convex-localfirst");
+    const outFile = join(outDir, "generated.ts");
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(outFile, emitManifestSource(schemaVersion, entries));
+    const tables = new Set(entries.map((e) => e.tableMeta.table));
+    console.log(`convex-localfirst codegen: wrote ${outFile} (${entries.length} functions across ${tables.size} table(s)).`);
+}
+// Coverage: regex catches ctx.db.insert("<lfTable>", …); an AST taint pass catches
+// ctx.db.patch/delete/replace on ids that provably come from a local-first table
+// (handler `v.id("lf")` args, `const doc = await ctx.db.query("lf")…first()`, and
+// inline query-then-write). The pass is sound (no false positives) but function-scoped:
+// ids passed across function boundaries or through ctx.db.get() are not traced.
+const CHECK_SCOPE_NOTE = "note: catches ctx.db.insert + id-based patch/delete/replace whose id is traceable to a local-first table within one function; ids passed across functions or via ctx.db.get() are not traced — review those manually.";
+function check() {
+    const dir = existsSync("convex") ? "convex" : ".";
+    const violations = runCheck(dir);
+    if (violations.length === 0) {
+        console.log("convex-localfirst check: no direct writes to local-first tables found");
+        console.log(`convex-localfirst check: ${CHECK_SCOPE_NOTE}`);
+        return;
+    }
+    console.error(`convex-localfirst check: found ${violations.length} direct write(s) to local-first tables:`);
+    for (const v of violations) {
+        console.error(`  ${v.file}:${v.line}  ctx.db.${v.method}("${v.table}", ...)  — use the generated wrapper`);
+        console.error(`    ${v.snippet}`);
+    }
+    console.error(`convex-localfirst check: ${CHECK_SCOPE_NOTE}`);
+    process.exitCode = 1;
+}
+async function dev() {
+    // The dev-time pipeline: regenerate the client manifest from the DSL, then
+    // statically verify nothing writes a local-first table directly. The Convex
+    // backend itself is run separately with `npx convex dev`.
+    console.log("convex-localfirst dev: regenerating manifest + checking for direct local-first writes…");
+    await codegen();
+    check();
+    console.log("convex-localfirst dev: done. Run `npx convex dev` for the backend and live sync.");
+}
+function help() {
+    console.log(`convex-localfirst commands:
+  init
+  codegen
+  check
+  dev`);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@convex-localfirst/cli",
+  "version": "0.1.0",
+  "description": "CLI for convex-localfirst: codegen (client manifest from lf.table), check (catch direct LF-table writes), dev.",
+  "license": "MIT",
+  "keywords": [
+    "convex",
+    "local-first",
+    "cli",
+    "codegen"
+  ],
+  "type": "module",
+  "bin": {
+    "convex-localfirst": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "convex": ">=1.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "@convex-localfirst/server": "^0.1.0",
+    "@convex-localfirst/core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly false",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}