@yinzuoweia/nis 0.1.0

package/dist/core.js

@@ -0,0 +1,614 @@
+import { copyFile, mkdir, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import { CliError } from './errors.js';
+import { generateNodeId } from './id.js';
+import { withFileLock } from './lock.js';
+import { matchesNode, parseQuery } from './query.js';
+import { createInitialTree, fileExists, getLockPath, readTree, resolveTreePath, snapshotDir, writeTreeAtomic } from './storage.js';
+import { RESERVED_FIELDS, ROOT_ID } from './types.js';
+function defaultSnapshotKeep() {
+    const raw = process.env.NIS_SNAPSHOT_KEEP;
+    if (!raw) {
+        return 20;
+    }
+    const parsed = Number(raw);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        return 20;
+    }
+    return Math.floor(parsed);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function ensureMutableField(key) {
+    if (RESERVED_FIELDS.has(key)) {
+        throw new CliError('SCHEMA_INVALID', `field '${key}' is reserved and cannot be modified directly`);
+    }
+}
+function assertNodeExists(tree, nodeId) {
+    const node = tree.nodes[nodeId];
+    if (!node) {
+        throw new CliError('NODE_NOT_FOUND', `node '${nodeId}' not found`, `use find with id:${nodeId}`);
+    }
+    return node;
+}
+function assertNodeIdAvailable(tree, nodeId) {
+    if (tree.nodes[nodeId]) {
+        throw new CliError('NODE_ID_CONFLICT', `node id '${nodeId}' already exists`);
+    }
+    if (nodeId === ROOT_ID) {
+        throw new CliError('NODE_ID_CONFLICT', `node id '${ROOT_ID}' is reserved`);
+    }
+}
+function collectSubtreeIds(tree, nodeId) {
+    const result = [];
+    const stack = [nodeId];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        result.push(current);
+        const node = assertNodeExists(tree, current);
+        for (const childId of node.children) {
+            stack.push(childId);
+        }
+    }
+    return result;
+}
+function removeFromParent(tree, nodeId) {
+    const node = assertNodeExists(tree, nodeId);
+    if (!node.parent) {
+        return;
+    }
+    const parent = assertNodeExists(tree, node.parent);
+    parent.children = parent.children.filter((id) => id !== nodeId);
+    parent.updated_at = nowIso();
+}
+function addToParent(tree, nodeId, parentId) {
+    const parent = assertNodeExists(tree, parentId);
+    if (!parent.children.includes(nodeId)) {
+        parent.children.push(nodeId);
+    }
+    parent.updated_at = nowIso();
+}
+function isDescendant(tree, ancestorId, maybeDescendant) {
+    if (ancestorId === maybeDescendant) {
+        return true;
+    }
+    const stack = [ancestorId];
+    const visited = new Set();
+    while (stack.length > 0) {
+        const id = stack.pop();
+        if (visited.has(id)) {
+            continue;
+        }
+        visited.add(id);
+        const node = assertNodeExists(tree, id);
+        for (const childId of node.children) {
+            if (childId === maybeDescendant) {
+                return true;
+            }
+            stack.push(childId);
+        }
+    }
+    return false;
+}
+function parseSort(sortRaw) {
+    if (!sortRaw) {
+        return null;
+    }
+    const [field, directionRaw] = sortRaw.split(':');
+    const direction = directionRaw?.toLowerCase() === 'asc' ? 'asc' : 'desc';
+    if (!field) {
+        return null;
+    }
+    return { field, direction };
+}
+function valueForSort(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const date = Date.parse(value);
+        if (!Number.isNaN(date)) {
+            return date;
+        }
+        const num = Number(value);
+        if (!Number.isNaN(num)) {
+            return num;
+        }
+        return value.toLowerCase();
+    }
+    return String(value).toLowerCase();
+}
+async function createSnapshotInternal(filePath, name) {
+    const snapDir = snapshotDir(filePath);
+    await mkdir(snapDir, { recursive: true });
+    const base = name && name.trim().length > 0 ? name.replace(/[^a-zA-Z0-9_-]/g, '_') : 'snapshot';
+    const snapshotId = `${Date.now()}-${base}.json`;
+    const snapPath = join(snapDir, snapshotId);
+    await copyFile(filePath, snapPath);
+    return {
+        snapshot_id: snapshotId,
+        path: snapPath
+    };
+}
+async function pruneSnapshots(filePath, keep) {
+    if (keep <= 0) {
+        return;
+    }
+    const snapDir = snapshotDir(filePath);
+    const entries = await readdir(snapDir, { withFileTypes: true }).catch(() => []);
+    const files = entries.filter((entry) => entry.isFile()).map((entry) => join(snapDir, entry.name));
+    if (files.length <= keep) {
+        return;
+    }
+    const withTime = await Promise.all(files.map(async (file) => {
+        const info = await stat(file);
+        return { file, mtimeMs: info.mtimeMs };
+    }));
+    withTime.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const toDelete = withTime.slice(keep);
+    await Promise.all(toDelete.map(async (item) => rm(item.file, { force: true })));
+}
+async function mutateWithLock(filePathRaw, mutator, options = {}) {
+    const filePath = resolveTreePath({ filePath: filePathRaw });
+    const lockPath = getLockPath(filePath);
+    return withFileLock(lockPath, async () => {
+        const tree = await readTree(filePath);
+        if (options.autoSnapshot !== false) {
+            await createSnapshotInternal(filePath, 'autosave');
+            await pruneSnapshots(filePath, options.snapshotKeep ?? defaultSnapshotKeep());
+        }
+        const out = await mutator(tree);
+        await writeTreeAtomic(filePath, tree);
+        return out;
+    });
+}
+function addNodeOnTree(tree, input) {
+    const parentId = input.parent ?? ROOT_ID;
+    assertNodeExists(tree, parentId);
+    const nodeId = input.id ?? generateNodeId(new Set(Object.keys(tree.nodes)));
+    assertNodeIdAvailable(tree, nodeId);
+    const ts = nowIso();
+    const extra = {};
+    for (const [key, value] of Object.entries(input.set ?? {})) {
+        ensureMutableField(key);
+        extra[key] = value;
+    }
+    tree.nodes[nodeId] = {
+        id: nodeId,
+        parent: parentId,
+        children: [],
+        created_at: ts,
+        updated_at: ts,
+        ...extra
+    };
+    addToParent(tree, nodeId, parentId);
+    return { id: nodeId, parent: parentId };
+}
+function updateNodeOnTree(tree, nodeId, patch) {
+    const node = assertNodeExists(tree, nodeId);
+    for (const key of Object.keys(patch.set ?? {})) {
+        ensureMutableField(key);
+    }
+    for (const key of patch.unset ?? []) {
+        ensureMutableField(key);
+    }
+    for (const [key, value] of Object.entries(patch.set ?? {})) {
+        node[key] = value;
+    }
+    for (const key of patch.unset ?? []) {
+        delete node[key];
+    }
+    node.updated_at = nowIso();
+    return node;
+}
+function deleteNodeOnTree(tree, nodeId, input) {
+    if (nodeId === ROOT_ID) {
+        throw new CliError('ROOT_IMMUTABLE', 'root node cannot be deleted');
+    }
+    const node = assertNodeExists(tree, nodeId);
+    if (!input.cascade && node.children.length > 0) {
+        throw new CliError('DELETE_CONFIRM_REQUIRED', 'node has children, use --cascade to delete subtree');
+    }
+    const ids = collectSubtreeIds(tree, nodeId);
+    removeFromParent(tree, nodeId);
+    for (const id of ids) {
+        delete tree.nodes[id];
+    }
+    return { deleted_ids: ids };
+}
+function moveNodeOnTree(tree, nodeId, targetParentId) {
+    if (nodeId === ROOT_ID) {
+        throw new CliError('ROOT_IMMUTABLE', 'root node cannot be moved');
+    }
+    const node = assertNodeExists(tree, nodeId);
+    assertNodeExists(tree, targetParentId);
+    if (isDescendant(tree, nodeId, targetParentId)) {
+        throw new CliError('CYCLE_DETECTED', `cannot move '${nodeId}' under '${targetParentId}'`);
+    }
+    const oldParent = node.parent;
+    removeFromParent(tree, nodeId);
+    node.parent = targetParentId;
+    node.updated_at = nowIso();
+    addToParent(tree, nodeId, targetParentId);
+    return {
+        id: nodeId,
+        from: oldParent,
+        to: targetParentId
+    };
+}
+function validateTreeObject(tree) {
+    const errors = [];
+    const warnings = [];
+    if (tree.root_id !== ROOT_ID) {
+        errors.push(`root_id must be '${ROOT_ID}'`);
+    }
+    const root = tree.nodes[ROOT_ID];
+    if (!root) {
+        errors.push('root node missing');
+    }
+    else {
+        if (root.parent !== null) {
+            errors.push('root.parent must be null');
+        }
+    }
+    for (const [id, node] of Object.entries(tree.nodes)) {
+        if (node.id !== id) {
+            errors.push(`node key '${id}' != node.id '${node.id}'`);
+        }
+        if (id !== ROOT_ID && node.parent === null) {
+            errors.push(`node '${id}' parent cannot be null`);
+        }
+        if (node.parent) {
+            const parent = tree.nodes[node.parent];
+            if (!parent) {
+                errors.push(`node '${id}' parent '${node.parent}' not found`);
+            }
+            else if (!parent.children.includes(id)) {
+                errors.push(`node '${id}' missing in parent '${node.parent}' children`);
+            }
+        }
+        for (const childId of node.children) {
+            const child = tree.nodes[childId];
+            if (!child) {
+                errors.push(`node '${id}' child '${childId}' not found`);
+                continue;
+            }
+            if (child.parent !== id) {
+                errors.push(`node '${childId}' parent mismatch, expected '${id}' got '${child.parent}'`);
+            }
+        }
+    }
+    const visited = new Set();
+    const stack = new Set();
+    function dfs(id) {
+        if (stack.has(id)) {
+            errors.push(`cycle detected at '${id}'`);
+            return;
+        }
+        if (visited.has(id)) {
+            return;
+        }
+        visited.add(id);
+        stack.add(id);
+        const node = tree.nodes[id];
+        for (const childId of node.children) {
+            if (tree.nodes[childId]) {
+                dfs(childId);
+            }
+        }
+        stack.delete(id);
+    }
+    if (tree.nodes[ROOT_ID]) {
+        dfs(ROOT_ID);
+    }
+    for (const id of Object.keys(tree.nodes)) {
+        if (!visited.has(id)) {
+            warnings.push(`node '${id}' is disconnected from root`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+function normalizeOps(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && typeof raw === 'object' && Array.isArray(raw.ops)) {
+        return raw.ops;
+    }
+    throw new CliError('SCHEMA_INVALID', 'bulk ops file must be an array or {ops: []}');
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new CliError('SCHEMA_INVALID', 'expected object value in bulk operation');
+    }
+    return value;
+}
+function applyOneBulkOp(tree, op) {
+    const action = String(op.action ?? '');
+    switch (action) {
+        case 'add': {
+            return addNodeOnTree(tree, {
+                parent: typeof op.parent === 'string' ? op.parent : ROOT_ID,
+                id: typeof op.id === 'string' ? op.id : undefined,
+                set: asRecord(op.set ?? {})
+            });
+        }
+        case 'update': {
+            if (typeof op.id !== 'string') {
+                throw new CliError('SCHEMA_INVALID', 'update operation requires id');
+            }
+            return updateNodeOnTree(tree, op.id, {
+                set: asRecord(op.set ?? {}),
+                unset: Array.isArray(op.unset) ? op.unset.map(String) : []
+            });
+        }
+        case 'delete': {
+            if (typeof op.id !== 'string') {
+                throw new CliError('SCHEMA_INVALID', 'delete operation requires id');
+            }
+            if (op.yes !== true) {
+                throw new CliError('DELETE_CONFIRM_REQUIRED', 'bulk delete requires yes=true');
+            }
+            return deleteNodeOnTree(tree, op.id, { cascade: op.cascade !== false, yes: true });
+        }
+        case 'move': {
+            if (typeof op.id !== 'string' || typeof op.to !== 'string') {
+                throw new CliError('SCHEMA_INVALID', 'move operation requires id and to');
+            }
+            return moveNodeOnTree(tree, op.id, op.to);
+        }
+        case 'upsert': {
+            if (typeof op.id !== 'string') {
+                throw new CliError('SCHEMA_INVALID', 'upsert operation requires id');
+            }
+            const set = asRecord(op.set ?? {});
+            if (tree.nodes[op.id]) {
+                const updated = updateNodeOnTree(tree, op.id, { set });
+                if (typeof op.parent === 'string' && updated.parent !== op.parent) {
+                    moveNodeOnTree(tree, op.id, op.parent);
+                }
+                return { id: op.id, created: false };
+            }
+            addNodeOnTree(tree, {
+                id: op.id,
+                parent: typeof op.parent === 'string' ? op.parent : ROOT_ID,
+                set
+            });
+            return { id: op.id, created: true };
+        }
+        default:
+            throw new CliError('SCHEMA_INVALID', `unsupported bulk action '${action}'`);
+    }
+}
+export async function initTree(filePathRaw, options = {}) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const lockPath = getLockPath(file);
+    return withFileLock(lockPath, async () => {
+        const exists = await fileExists(file);
+        if (exists && !options.force) {
+            throw new CliError('SCHEMA_INVALID', `tree file already exists: ${file}`, 'use --force to overwrite');
+        }
+        await mkdir(dirname(file), { recursive: true });
+        const tree = createInitialTree();
+        await writeTreeAtomic(file, tree);
+        return {
+            file,
+            root_id: ROOT_ID
+        };
+    });
+}
+export async function addNode(filePathRaw, input, options = {}) {
+    return mutateWithLock(filePathRaw, (tree) => addNodeOnTree(tree, input), options);
+}
+export async function getNode(filePathRaw, nodeId) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const tree = await readTree(file);
+    return assertNodeExists(tree, nodeId);
+}
+export async function listChildren(filePathRaw, parentId = ROOT_ID, max) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const tree = await readTree(file);
+    const parent = assertNodeExists(tree, parentId);
+    const children = parent.children.map((childId) => assertNodeExists(tree, childId));
+    return typeof max === 'number' ? children.slice(0, max) : children;
+}
+export async function updateNode(filePathRaw, nodeId, input, options = {}) {
+    return mutateWithLock(filePathRaw, (tree) => updateNodeOnTree(tree, nodeId, input), options);
+}
+export async function deleteNode(filePathRaw, nodeId, input, options = {}) {
+    if (!input.yes) {
+        const file = resolveTreePath({ filePath: filePathRaw });
+        const tree = await readTree(file);
+        if (nodeId === ROOT_ID) {
+            throw new CliError('ROOT_IMMUTABLE', 'root node cannot be deleted');
+        }
+        assertNodeExists(tree, nodeId);
+        const ids = collectSubtreeIds(tree, nodeId);
+        return {
+            requires_confirmation: true,
+            count: ids.length,
+            ids
+        };
+    }
+    return mutateWithLock(filePathRaw, (tree) => deleteNodeOnTree(tree, nodeId, { cascade: input.cascade !== false, yes: true }), options);
+}
+export async function moveNode(filePathRaw, nodeId, newParentId, options = {}) {
+    return mutateWithLock(filePathRaw, (tree) => moveNodeOnTree(tree, nodeId, newParentId), options);
+}
+export async function findNodesInternal(filePathRaw, input) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const tree = await readTree(file);
+    const parsed = parseQuery(input.query ?? '');
+    let nodes = Object.values(tree.nodes).filter((node) => matchesNode(node, parsed, new Date()));
+    const sort = parseSort(input.sort);
+    if (sort) {
+        nodes = nodes.sort((a, b) => {
+            const av = valueForSort(a[sort.field]);
+            const bv = valueForSort(b[sort.field]);
+            if (av < bv) {
+                return sort.direction === 'asc' ? -1 : 1;
+            }
+            if (av > bv) {
+                return sort.direction === 'asc' ? 1 : -1;
+            }
+            return 0;
+        });
+    }
+    if (typeof input.max === 'number') {
+        nodes = nodes.slice(0, input.max);
+    }
+    if (input.fields && input.fields.length > 0) {
+        return nodes.map((node) => {
+            const picked = {};
+            for (const field of input.fields ?? []) {
+                picked[field] = node[field];
+            }
+            return picked;
+        });
+    }
+    return nodes;
+}
+export async function validateTree(filePathRaw) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const tree = await readTree(file);
+    return validateTreeObject(tree);
+}
+export async function upsertNode(filePathRaw, input, options = {}) {
+    return mutateWithLock(filePathRaw, (tree) => {
+        const parent = input.parent ?? ROOT_ID;
+        if (tree.nodes[input.id]) {
+            updateNodeOnTree(tree, input.id, { set: input.set });
+            const current = tree.nodes[input.id];
+            if (current.parent !== parent) {
+                moveNodeOnTree(tree, input.id, parent);
+            }
+            return { id: input.id, created: false, parent };
+        }
+        addNodeOnTree(tree, { id: input.id, parent, set: input.set });
+        return { id: input.id, created: true, parent };
+    }, options);
+}
+export async function applyBulkFromFile(filePathRaw, input, options = {}) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const lockPath = getLockPath(file);
+    return withFileLock(lockPath, async () => {
+        const tree = await readTree(file);
+        const opsRaw = JSON.parse(await readFile(input.opsFile, 'utf-8'));
+        const ops = normalizeOps(opsRaw);
+        let atomicSnapshot = null;
+        if (input.atomic !== false) {
+            atomicSnapshot = await createSnapshotInternal(file, 'bulk-atomic');
+        }
+        else if (options.autoSnapshot !== false) {
+            await createSnapshotInternal(file, 'autosave');
+        }
+        const results = [];
+        try {
+            for (const op of ops) {
+                const result = applyOneBulkOp(tree, op);
+                results.push(result);
+            }
+            await writeTreeAtomic(file, tree);
+            await pruneSnapshots(file, options.snapshotKeep ?? defaultSnapshotKeep());
+            return {
+                applied: ops.length,
+                results
+            };
+        }
+        catch (err) {
+            if (atomicSnapshot) {
+                await copyFile(atomicSnapshot.path, file);
+            }
+            throw err;
+        }
+    });
+}
+export async function createSnapshot(filePathRaw, name) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const lockPath = getLockPath(file);
+    return withFileLock(lockPath, async () => {
+        await readTree(file);
+        const info = await createSnapshotInternal(file, name);
+        await pruneSnapshots(file, defaultSnapshotKeep());
+        return info;
+    });
+}
+export async function restoreSnapshot(filePathRaw, snapshotId) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const lockPath = getLockPath(file);
+    return withFileLock(lockPath, async () => {
+        const snapPath = join(snapshotDir(file), snapshotId);
+        const exists = await fileExists(snapPath);
+        if (!exists) {
+            throw new CliError('FILE_NOT_FOUND', `snapshot '${snapshotId}' not found`);
+        }
+        await mkdir(dirname(file), { recursive: true });
+        await copyFile(snapPath, file);
+        return { restored: snapshotId };
+    });
+}
+export async function listSnapshots(filePathRaw) {
+    const file = resolveTreePath({ filePath: filePathRaw });
+    const dir = snapshotDir(file);
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+}
+export function parseSetPairs(pairs = []) {
+    const out = {};
+    for (const pair of pairs) {
+        const index = pair.indexOf('=');
+        if (index <= 0) {
+            throw new CliError('SCHEMA_INVALID', `invalid --set pair '${pair}', expected key=value`);
+        }
+        const key = pair.slice(0, index).trim();
+        const valueRaw = pair.slice(index + 1).trim();
+        if (!key) {
+            throw new CliError('SCHEMA_INVALID', `invalid --set pair '${pair}', missing key`);
+        }
+        let value = valueRaw;
+        if (valueRaw === 'null') {
+            value = null;
+        }
+        else if (valueRaw === 'true') {
+            value = true;
+        }
+        else if (valueRaw === 'false') {
+            value = false;
+        }
+        else if (!Number.isNaN(Number(valueRaw)) && valueRaw.length > 0) {
+            value = Number(valueRaw);
+        }
+        else {
+            try {
+                if ((valueRaw.startsWith('{') && valueRaw.endsWith('}')) || (valueRaw.startsWith('[') && valueRaw.endsWith(']'))) {
+                    value = JSON.parse(valueRaw);
+                }
+            }
+            catch {
+                value = valueRaw;
+            }
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export function parseSparkExpression(expression) {
+    const pairs = expression.match(/"[^"]+"|'[^']+'|\S+/g) ?? [];
+    const normalized = pairs.map((part) => {
+        const token = part.startsWith('"') || part.startsWith("'") ? part.slice(1, -1) : part;
+        const idx = token.indexOf(':');
+        if (idx <= 0) {
+            throw new CliError('SCHEMA_INVALID', `invalid spark token '${token}', expected key:value`);
+        }
+        return `${token.slice(0, idx)}=${token.slice(idx + 1)}`;
+    });
+    return parseSetPairs(normalized);
+}
+export function snapshotIdFromPath(pathValue) {
+    return parse(pathValue).base;
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorCode } from './types.js';
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly hint?: string;
+    constructor(code: ErrorCode, message: string, hint?: string);
+}
+export declare function isNodeErrorWithCode(err: unknown): err is NodeJS.ErrnoException;

package/dist/errors.js

@@ -0,0 +1,12 @@
+export class CliError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export function isNodeErrorWithCode(err) {
+    return Boolean(err && typeof err === 'object' && 'code' in err);
+}

package/dist/id.d.ts

@@ -0,0 +1 @@
+export declare function generateNodeId(existing: Set<string>): string;

package/dist/id.js

@@ -0,0 +1,9 @@
+export function generateNodeId(existing) {
+    for (let i = 0; i < 20; i += 1) {
+        const id = `n_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+        if (!existing.has(id)) {
+            return id;
+        }
+    }
+    throw new Error('failed to generate unique node id');
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './api.js';
+export * from './errors.js';
+export * from './query.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './api.js';
+export * from './errors.js';
+export * from './query.js';
+export * from './types.js';

package/dist/lock.d.ts

@@ -0,0 +1,6 @@
+export type LockOptions = {
+    timeoutMs?: number;
+    retryMs?: number;
+    staleMs?: number;
+};
+export declare function withFileLock<T>(lockPath: string, fn: () => Promise<T>, options?: LockOptions): Promise<T>;