@yinzuoweia/nis 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# NIS (`@yinzuoweia/nis`)
+
+Agent-friendly JSON tree CLI and JS API.
+
+## Install
+
+```bash
+npm i @yinzuoweia/nis
+```
+
+## CLI
+
+Default file path: `./.nis/tree.json`
+
+```bash
+nis init [--file <path>] [--force]
+nis add --set key=value... [--parent <id>] [--id <id>] [--file <path>]
+nis get <id> [--file <path>]
+nis ls [parentId] [--max <n>] [--file <path>]
+nis update <id> [--set key=value...] [--unset key...] [--file <path>]
+nis delete <id> [--cascade|--no-cascade] [--yes] [--file <path>]
+nis move <id> --to <newParentId> [--file <path>]
+nis find "<query>" [--max <n>] [--sort <field:asc|desc>] [--fields <csv>] [--file <path>]
+nis validate [--file <path>]
+nis upsert --id <id> --set key=value... [--parent <id>] [--file <path>]
+nis bulk --ops-file <json> [--atomic|--no-atomic] [--file <path>]
+nis snapshot create [--name <name>] [--file <path>]
+nis snapshot restore <snapshotId> [--file <path>]
+```
+
+### Natural aliases (`spark`)
+
+```bash
+nis spark search "newer_than:7d tag:idea" --max 10
+nis spark add "summary:idea description:detail" under root
+nis spark delete <id> --yes
+```
+
+## Query DSL (v1)
+
+- Full text term: `transformer`
+- Field filter: `tag:idea`
+- Comparators: `score>=0.9`, `updated_at>2026-03-01`
+- Relative time: `newer_than:7d`, `older_than:30d`
+- Multiple conditions are AND.
+
+## JS API
+
+```ts
+import {
+  initTree,
+  addNode,
+  updateNode,
+  deleteNode,
+  moveNode,
+  findNodes,
+  validateTree,
+  applyBulk,
+  createSnapshot,
+  restoreSnapshot,
+} from '@yinzuoweia/nis';
+```
+
+## Output Contract
+
+CLI always writes machine-readable JSON:
+
+- success: `{"ok": true, "action": "...", "file": "...", "result": ..., "warnings": []}`
+- error: `{"ok": false, "action": "...", "error": {"code": "...", "message": "...", "hint": "..."}}`
+
+## Notes
+
+- Root node is fixed as `root` and immutable.
+- Reserved fields: `id,parent,children,created_at,updated_at`.
+- Writes are protected by file lock + atomic rename.
+- Snapshot retention default is `20` and can be configured with `NIS_SNAPSHOT_KEEP`.

package/dist/api.d.ts

@@ -0,0 +1,15 @@
+import { addNode, createSnapshot, deleteNode, getNode, initTree, listChildren, moveNode, parseSetPairs, parseSparkExpression, restoreSnapshot, updateNode, upsertNode, validateTree } from './core.js';
+import type { AddInput, BulkInput, DeleteInput, FindInput, InitOptions, MutateOptions, SnapshotInfo, UpdateInput } from './core.js';
+export { initTree, addNode, getNode, listChildren, updateNode, deleteNode, moveNode, validateTree, upsertNode, createSnapshot, restoreSnapshot, parseSetPairs, parseSparkExpression };
+export type { InitOptions, AddInput, UpdateInput, DeleteInput, FindInput, BulkInput, SnapshotInfo, MutateOptions };
+export declare function findNodes(filePath: string | undefined, query: string, options?: Omit<FindInput, 'query'>): Promise<Array<Record<string, unknown>>>;
+export declare function applyBulk(filePath: string | undefined, ops: Array<Record<string, unknown>>, options?: Omit<MutateOptions, 'autoSnapshot'> & {
+    atomic?: boolean;
+}): Promise<{
+    applied: number;
+    results: Array<Record<string, unknown>>;
+}>;
+export declare function applyBulkFromOpsFile(filePath: string | undefined, input: BulkInput, options?: MutateOptions): Promise<{
+    applied: number;
+    results: Array<Record<string, unknown>>;
+}>;

package/dist/api.js

@@ -0,0 +1,29 @@
+import { rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { addNode, applyBulkFromFile, createSnapshot, deleteNode, findNodesInternal, getNode, initTree, listChildren, moveNode, parseSetPairs, parseSparkExpression, restoreSnapshot, updateNode, upsertNode, validateTree } from './core.js';
+export { initTree, addNode, getNode, listChildren, updateNode, deleteNode, moveNode, validateTree, upsertNode, createSnapshot, restoreSnapshot, parseSetPairs, parseSparkExpression };
+export async function findNodes(filePath, query, options = {}) {
+    return findNodesInternal(filePath, {
+        query,
+        ...options
+    });
+}
+export async function applyBulk(filePath, ops, options = {}) {
+    const tempOpsFile = join(tmpdir(), `.nis-bulk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+    await writeFile(tempOpsFile, JSON.stringify(ops), 'utf-8');
+    try {
+        return await applyBulkFromFile(filePath, {
+            opsFile: tempOpsFile,
+            atomic: options.atomic
+        }, {
+            snapshotKeep: options.snapshotKeep
+        });
+    }
+    finally {
+        await rm(tempOpsFile, { force: true });
+    }
+}
+export async function applyBulkFromOpsFile(filePath, input, options = {}) {
+    return applyBulkFromFile(filePath, input, options);
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { CliError } from './errors.js';
+import { addNode, applyBulkFromOpsFile, createSnapshot, deleteNode, findNodes, getNode, initTree, listChildren, moveNode, parseSetPairs, parseSparkExpression, restoreSnapshot, updateNode, upsertNode, validateTree } from './api.js';
+const EXIT_MAP = {
+    FILE_NOT_FOUND: 2,
+    SCHEMA_INVALID: 3,
+    NODE_NOT_FOUND: 4,
+    NODE_ID_CONFLICT: 5,
+    ROOT_IMMUTABLE: 6,
+    DELETE_CONFIRM_REQUIRED: 7,
+    CYCLE_DETECTED: 8,
+    LOCK_TIMEOUT: 9
+};
+function outputSuccess(action, file, result, warnings = []) {
+    const payload = {
+        ok: true,
+        action,
+        file,
+        result,
+        warnings
+    };
+    console.log(JSON.stringify(payload));
+}
+function outputError(action, err) {
+    if (err instanceof CliError) {
+        const payload = {
+            ok: false,
+            action,
+            error: {
+                code: err.code,
+                message: err.message,
+                hint: err.hint
+            }
+        };
+        console.error(JSON.stringify(payload));
+        process.exit(EXIT_MAP[err.code] ?? 1);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    const payload = {
+        ok: false,
+        action,
+        error: {
+            code: 'UNKNOWN',
+            message
+        }
+    };
+    console.error(JSON.stringify(payload));
+    process.exit(1);
+}
+const program = new Command();
+program.name('nis').description('NIS CLI for JSON tree operations').version('0.1.0');
+program
+    .command('init')
+    .option('--file <path>')
+    .option('--force', 'overwrite existing tree')
+    .action(async (opts) => {
+    try {
+        const result = await initTree(opts.file, { force: Boolean(opts.force) });
+        outputSuccess('init', result.file, result);
+    }
+    catch (err) {
+        outputError('init', err);
+    }
+});
+program
+    .command('add')
+    .requiredOption('--set <pair...>', 'key=value pairs')
+    .option('--file <path>')
+    .option('--parent <id>')
+    .option('--id <id>')
+    .action(async (opts) => {
+    try {
+        const result = await addNode(opts.file, {
+            parent: opts.parent,
+            id: opts.id,
+            set: parseSetPairs(opts.set)
+        });
+        outputSuccess('add', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('add', err);
+    }
+});
+program
+    .command('get')
+    .argument('<id>')
+    .option('--file <path>')
+    .action(async (id, opts) => {
+    try {
+        const result = await getNode(opts.file, id);
+        outputSuccess('get', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('get', err);
+    }
+});
+program
+    .command('ls')
+    .argument('[parentId]')
+    .option('--file <path>')
+    .option('--max <n>', 'limit', (v) => Number(v))
+    .action(async (parentId, opts) => {
+    try {
+        const result = await listChildren(opts.file, parentId, opts.max);
+        outputSuccess('ls', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('ls', err);
+    }
+});
+program
+    .command('update')
+    .argument('<id>')
+    .option('--file <path>')
+    .option('--set <pair...>')
+    .option('--unset <key...>')
+    .action(async (id, opts) => {
+    try {
+        const result = await updateNode(opts.file, id, {
+            set: parseSetPairs(opts.set ?? []),
+            unset: opts.unset ?? []
+        });
+        outputSuccess('update', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('update', err);
+    }
+});
+program
+    .command('delete')
+    .argument('<id>')
+    .option('--file <path>')
+    .option('--cascade', 'cascade delete')
+    .option('--no-cascade', 'disable cascade delete')
+    .option('--yes', 'confirm delete')
+    .action(async (id, opts) => {
+    try {
+        const result = await deleteNode(opts.file, id, { cascade: opts.cascade !== false, yes: Boolean(opts.yes) });
+        outputSuccess(opts.yes ? 'delete' : 'delete_preview', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('delete', err);
+    }
+});
+program
+    .command('move')
+    .argument('<id>')
+    .requiredOption('--to <id>')
+    .option('--file <path>')
+    .action(async (id, opts) => {
+    try {
+        const result = await moveNode(opts.file, id, opts.to);
+        outputSuccess('move', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('move', err);
+    }
+});
+program
+    .command('find')
+    .argument('<query>')
+    .option('--file <path>')
+    .option('--max <n>', 'limit', (v) => Number(v))
+    .option('--sort <spec>')
+    .option('--fields <csv>')
+    .action(async (query, opts) => {
+    try {
+        const fields = typeof opts.fields === 'string' ? opts.fields.split(',').map((f) => f.trim()).filter(Boolean) : undefined;
+        const result = await findNodes(opts.file, query, {
+            max: opts.max,
+            sort: opts.sort,
+            fields
+        });
+        outputSuccess('find', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('find', err);
+    }
+});
+program
+    .command('validate')
+    .option('--file <path>')
+    .action(async (opts) => {
+    try {
+        const result = await validateTree(opts.file);
+        outputSuccess('validate', opts.file ?? '.nis/tree.json', result, result.warnings);
+    }
+    catch (err) {
+        outputError('validate', err);
+    }
+});
+program
+    .command('upsert')
+    .requiredOption('--id <id>')
+    .requiredOption('--set <pair...>')
+    .option('--parent <id>')
+    .option('--file <path>')
+    .action(async (opts) => {
+    try {
+        const result = await upsertNode(opts.file, {
+            id: opts.id,
+            parent: opts.parent,
+            set: parseSetPairs(opts.set)
+        });
+        outputSuccess('upsert', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('upsert', err);
+    }
+});
+program
+    .command('bulk')
+    .requiredOption('--ops-file <path>')
+    .option('--file <path>')
+    .option('--atomic', 'enable atomic rollback')
+    .option('--no-atomic', 'disable atomic rollback')
+    .action(async (opts) => {
+    try {
+        const result = await applyBulkFromOpsFile(opts.file, { opsFile: opts.opsFile, atomic: opts.atomic !== false });
+        outputSuccess('bulk', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('bulk', err);
+    }
+});
+const snapshot = program.command('snapshot');
+snapshot
+    .command('create')
+    .option('--file <path>')
+    .option('--name <name>')
+    .action(async (opts) => {
+    try {
+        const result = await createSnapshot(opts.file, opts.name);
+        outputSuccess('snapshot_create', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('snapshot_create', err);
+    }
+});
+snapshot
+    .command('restore')
+    .argument('<snapshotId>')
+    .option('--file <path>')
+    .action(async (snapshotId, opts) => {
+    try {
+        const result = await restoreSnapshot(opts.file, snapshotId);
+        outputSuccess('snapshot_restore', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('snapshot_restore', err);
+    }
+});
+const spark = program.command('spark').description('natural-language style aliases');
+spark
+    .command('search')
+    .argument('<query>')
+    .option('--file <path>')
+    .option('--max <n>', 'limit', (v) => Number(v))
+    .option('--sort <spec>')
+    .action(async (query, opts) => {
+    try {
+        const result = await findNodes(opts.file, query, {
+            max: opts.max,
+            sort: opts.sort
+        });
+        outputSuccess('find', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('find', err);
+    }
+});
+spark
+    .command('add')
+    .argument('<expression>')
+    .argument('[underKeyword]')
+    .argument('[parentId]')
+    .option('--file <path>')
+    .option('--id <id>')
+    .action(async (expression, underKeyword, parentId, opts) => {
+    try {
+        if (underKeyword && underKeyword !== 'under') {
+            throw new CliError('SCHEMA_INVALID', `expected keyword 'under', got '${underKeyword}'`);
+        }
+        const result = await addNode(opts.file, {
+            parent: parentId ?? 'root',
+            id: opts.id,
+            set: parseSparkExpression(expression)
+        });
+        outputSuccess('add', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('add', err);
+    }
+});
+spark
+    .command('delete')
+    .argument('<id>')
+    .option('--file <path>')
+    .option('--yes')
+    .action(async (id, opts) => {
+    try {
+        const result = await deleteNode(opts.file, id, {
+            cascade: true,
+            yes: Boolean(opts.yes)
+        });
+        outputSuccess(opts.yes ? 'delete' : 'delete_preview', opts.file ?? '.nis/tree.json', result);
+    }
+    catch (err) {
+        outputError('delete', err);
+    }
+});
+await program.parseAsync(process.argv);

package/dist/core.d.ts

@@ -0,0 +1,84 @@
+import { type TreeNode } from './types.js';
+export type MutateOptions = {
+    autoSnapshot?: boolean;
+    snapshotKeep?: number;
+};
+export type InitOptions = {
+    force?: boolean;
+};
+export type AddInput = {
+    parent?: string;
+    id?: string;
+    set: Record<string, unknown>;
+};
+export type UpdateInput = {
+    set?: Record<string, unknown>;
+    unset?: string[];
+};
+export type DeleteInput = {
+    cascade?: boolean;
+    yes?: boolean;
+};
+export type FindInput = {
+    query: string;
+    max?: number;
+    sort?: string;
+    fields?: string[];
+};
+export type BulkInput = {
+    opsFile: string;
+    atomic?: boolean;
+};
+export type SnapshotInfo = {
+    snapshot_id: string;
+    path: string;
+};
+export declare function initTree(filePathRaw?: string, options?: InitOptions): Promise<{
+    file: string;
+    root_id: string;
+}>;
+export declare function addNode(filePathRaw: string | undefined, input: AddInput, options?: MutateOptions): Promise<{
+    id: string;
+    parent: string;
+}>;
+export declare function getNode(filePathRaw: string | undefined, nodeId: string): Promise<TreeNode>;
+export declare function listChildren(filePathRaw: string | undefined, parentId?: string, max?: number): Promise<TreeNode[]>;
+export declare function updateNode(filePathRaw: string | undefined, nodeId: string, input: UpdateInput, options?: MutateOptions): Promise<TreeNode>;
+export declare function deleteNode(filePathRaw: string | undefined, nodeId: string, input: DeleteInput, options?: MutateOptions): Promise<{
+    requires_confirmation?: boolean;
+    count?: number;
+    ids?: string[];
+    deleted_ids?: string[];
+}>;
+export declare function moveNode(filePathRaw: string | undefined, nodeId: string, newParentId: string, options?: MutateOptions): Promise<{
+    id: string;
+    from: string | null;
+    to: string;
+}>;
+export declare function findNodesInternal(filePathRaw: string | undefined, input: FindInput): Promise<Array<Record<string, unknown>>>;
+export declare function validateTree(filePathRaw?: string): Promise<{
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}>;
+export declare function upsertNode(filePathRaw: string | undefined, input: {
+    id: string;
+    parent?: string;
+    set: Record<string, unknown>;
+}, options?: MutateOptions): Promise<{
+    id: string;
+    created: boolean;
+    parent: string;
+}>;
+export declare function applyBulkFromFile(filePathRaw: string | undefined, input: BulkInput, options?: MutateOptions): Promise<{
+    applied: number;
+    results: Array<Record<string, unknown>>;
+}>;
+export declare function createSnapshot(filePathRaw?: string, name?: string): Promise<SnapshotInfo>;
+export declare function restoreSnapshot(filePathRaw: string | undefined, snapshotId: string): Promise<{
+    restored: string;
+}>;
+export declare function listSnapshots(filePathRaw?: string): Promise<string[]>;
+export declare function parseSetPairs(pairs?: string[]): Record<string, unknown>;
+export declare function parseSparkExpression(expression: string): Record<string, unknown>;
+export declare function snapshotIdFromPath(pathValue: string): string;