@yinzuoweia/nis 0.1.0

package/dist/lock.js

@@ -0,0 +1,47 @@
+import { open, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { CliError, isNodeErrorWithCode } from './errors.js';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function removeIfStale(lockPath, staleMs) {
+    try {
+        const info = await stat(lockPath);
+        if (Date.now() - info.mtimeMs > staleMs) {
+            await rm(lockPath, { force: true });
+        }
+    }
+    catch {
+        // ignore
+    }
+}
+export async function withFileLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5000;
+    const retryMs = options.retryMs ?? 80;
+    const staleMs = options.staleMs ?? 30_000;
+    await mkdir(dirname(lockPath), { recursive: true });
+    const started = Date.now();
+    while (true) {
+        try {
+            const handle = await open(lockPath, 'wx');
+            try {
+                return await fn();
+            }
+            finally {
+                await handle.close();
+                await rm(lockPath, { force: true });
+            }
+        }
+        catch (err) {
+            if (!isNodeErrorWithCode(err) || err.code !== 'EEXIST') {
+                throw err;
+            }
+            await removeIfStale(lockPath, staleMs);
+            if (Date.now() - started > timeoutMs) {
+                throw new CliError('LOCK_TIMEOUT', `failed to acquire lock within ${timeoutMs}ms`, `lockPath=${lockPath}`);
+            }
+            await sleep(retryMs);
+        }
+    }
+}

package/dist/query.d.ts

@@ -0,0 +1,4 @@
+import type { ParsedQuery, TreeNode } from './types.js';
+export declare function parseDurationToMs(raw: string): number;
+export declare function parseQuery(query: string): ParsedQuery;
+export declare function matchesNode(node: TreeNode, parsed: ParsedQuery, now?: Date): boolean;

package/dist/query.js

@@ -0,0 +1,166 @@
+const COMPARE_RE = /^([^:<>!=\s]+)(>=|<=|>|<)(.+)$/;
+const FIELD_RE = /^([^:<>!=\s]+):(.+)$/;
+function tokenize(query) {
+    return query.match(/"[^"]+"|'[^']+'|\S+/g) ?? [];
+}
+function stripQuotes(raw) {
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    return raw;
+}
+export function parseDurationToMs(raw) {
+    const match = raw.trim().match(/^(\d+)([smhdw])$/i);
+    if (!match) {
+        return Number.NaN;
+    }
+    const value = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    const map = {
+        s: 1000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+        w: 604_800_000
+    };
+    return value * map[unit];
+}
+export function parseQuery(query) {
+    const terms = [];
+    const filters = [];
+    for (const tokenRaw of tokenize(query)) {
+        const token = stripQuotes(tokenRaw);
+        const lower = token.toLowerCase();
+        if (lower.startsWith('newer_than:')) {
+            const ms = parseDurationToMs(token.slice('newer_than:'.length));
+            if (!Number.isNaN(ms)) {
+                filters.push({ kind: 'relative', key: 'updated_at', direction: 'newer', ms });
+                continue;
+            }
+        }
+        if (lower.startsWith('older_than:')) {
+            const ms = parseDurationToMs(token.slice('older_than:'.length));
+            if (!Number.isNaN(ms)) {
+                filters.push({ kind: 'relative', key: 'updated_at', direction: 'older', ms });
+                continue;
+            }
+        }
+        const compare = token.match(COMPARE_RE);
+        if (compare) {
+            filters.push({
+                kind: 'compare',
+                key: compare[1],
+                op: compare[2],
+                value: compare[3]
+            });
+            continue;
+        }
+        const field = token.match(FIELD_RE);
+        if (field) {
+            filters.push({ kind: 'field', key: field[1], value: field[2] });
+            continue;
+        }
+        terms.push(token);
+    }
+    return { terms, filters };
+}
+function toComparable(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();
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    return String(value).toLowerCase();
+}
+function compareValues(left, rightRaw, op) {
+    const leftComp = toComparable(left);
+    const rightComp = toComparable(rightRaw);
+    if (typeof leftComp === 'number' && typeof rightComp === 'number') {
+        switch (op) {
+            case '>':
+                return leftComp > rightComp;
+            case '>=':
+                return leftComp >= rightComp;
+            case '<':
+                return leftComp < rightComp;
+            case '<=':
+                return leftComp <= rightComp;
+            default:
+                return false;
+        }
+    }
+    const leftStr = String(leftComp);
+    const rightStr = String(rightComp);
+    switch (op) {
+        case '>':
+            return leftStr > rightStr;
+        case '>=':
+            return leftStr >= rightStr;
+        case '<':
+            return leftStr < rightStr;
+        case '<=':
+            return leftStr <= rightStr;
+        default:
+            return false;
+    }
+}
+export function matchesNode(node, parsed, now = new Date()) {
+    const blob = Object.values(node)
+        .map((v) => (typeof v === 'string' ? v : ''))
+        .join(' ')
+        .toLowerCase();
+    for (const term of parsed.terms) {
+        if (!blob.includes(term.toLowerCase())) {
+            return false;
+        }
+    }
+    for (const filter of parsed.filters) {
+        if (filter.kind === 'field') {
+            const value = node[filter.key];
+            if (value === undefined || value === null) {
+                return false;
+            }
+            if (Array.isArray(value)) {
+                const found = value.some((item) => String(item).toLowerCase().includes(filter.value.toLowerCase()));
+                if (!found) {
+                    return false;
+                }
+            }
+            else if (!String(value).toLowerCase().includes(filter.value.toLowerCase())) {
+                return false;
+            }
+            continue;
+        }
+        if (filter.kind === 'compare') {
+            const value = node[filter.key];
+            if (value === undefined || !compareValues(value, filter.value, filter.op)) {
+                return false;
+            }
+            continue;
+        }
+        const updated = Date.parse(String(node.updated_at));
+        if (Number.isNaN(updated)) {
+            return false;
+        }
+        const threshold = now.getTime() - filter.ms;
+        if (filter.direction === 'newer' && !(updated >= threshold)) {
+            return false;
+        }
+        if (filter.direction === 'older' && !(updated <= threshold)) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/storage.d.ts

@@ -0,0 +1,12 @@
+import { type TreeFile } from './types.js';
+export type ResolvePathOptions = {
+    filePath?: string;
+};
+export declare function resolveTreePath(options?: ResolvePathOptions): string;
+export declare function getLockPath(filePath: string): string;
+export declare function snapshotDir(filePath: string): string;
+export declare function createInitialTree(now?: Date): TreeFile;
+export declare function readTree(filePath: string): Promise<TreeFile>;
+export declare function writeTreeAtomic(filePath: string, tree: TreeFile): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function removeFileIfExists(filePath: string): Promise<void>;

package/dist/storage.js

@@ -0,0 +1,96 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { CliError, isNodeErrorWithCode } from './errors.js';
+import { ROOT_ID } from './types.js';
+const nodeSchema = z
+    .object({
+    id: z.string().min(1),
+    parent: z.string().nullable(),
+    children: z.array(z.string()),
+    created_at: z.string(),
+    updated_at: z.string()
+})
+    .passthrough();
+const treeSchema = z.object({
+    version: z.string().min(1),
+    root_id: z.literal(ROOT_ID),
+    nodes: z.record(nodeSchema)
+});
+export function resolveTreePath(options = {}) {
+    if (options.filePath) {
+        return resolve(options.filePath);
+    }
+    return resolve('.nis/tree.json');
+}
+export function getLockPath(filePath) {
+    return `${filePath}.lock`;
+}
+export function snapshotDir(filePath) {
+    return join(dirname(filePath), 'snapshots');
+}
+export function createInitialTree(now = new Date()) {
+    const ts = now.toISOString();
+    return {
+        version: '1.0',
+        root_id: ROOT_ID,
+        nodes: {
+            [ROOT_ID]: {
+                id: ROOT_ID,
+                parent: null,
+                children: [],
+                created_at: ts,
+                updated_at: ts
+            }
+        }
+    };
+}
+export async function readTree(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        const validated = treeSchema.safeParse(parsed);
+        if (!validated.success) {
+            throw new CliError('SCHEMA_INVALID', 'tree file schema is invalid', validated.error.message);
+        }
+        return validated.data;
+    }
+    catch (err) {
+        if (isNodeErrorWithCode(err) && err.code === 'ENOENT') {
+            throw new CliError('FILE_NOT_FOUND', `tree file not found: ${filePath}`, 'run `nis init` first');
+        }
+        if (err instanceof CliError) {
+            throw err;
+        }
+        if (err instanceof SyntaxError) {
+            throw new CliError('SCHEMA_INVALID', 'tree file is not valid JSON', err.message);
+        }
+        throw err;
+    }
+}
+export async function writeTreeAtomic(filePath, tree) {
+    const validated = treeSchema.safeParse(tree);
+    if (!validated.success) {
+        throw new CliError('SCHEMA_INVALID', 'tree object is invalid', validated.error.message);
+    }
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(tempPath, JSON.stringify(validated.data, null, 2), 'utf-8');
+    await rename(tempPath, filePath);
+}
+export async function fileExists(filePath) {
+    try {
+        await readFile(filePath);
+        return true;
+    }
+    catch (err) {
+        if (isNodeErrorWithCode(err) && err.code === 'ENOENT') {
+            return false;
+        }
+        throw err;
+    }
+}
+export async function removeFileIfExists(filePath) {
+    await rm(filePath, { force: true });
+}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export declare const ROOT_ID = "root";
+export declare const RESERVED_FIELDS: Set<string>;
+export type ErrorCode = 'FILE_NOT_FOUND' | 'SCHEMA_INVALID' | 'NODE_NOT_FOUND' | 'NODE_ID_CONFLICT' | 'ROOT_IMMUTABLE' | 'DELETE_CONFIRM_REQUIRED' | 'CYCLE_DETECTED' | 'LOCK_TIMEOUT';
+export type TreeNode = {
+    id: string;
+    parent: string | null;
+    children: string[];
+    created_at: string;
+    updated_at: string;
+    [key: string]: unknown;
+};
+export type TreeFile = {
+    version: string;
+    root_id: typeof ROOT_ID;
+    nodes: Record<string, TreeNode>;
+};
+export type QueryComparator = '>' | '>=' | '<' | '<=';
+export type QueryFilter = {
+    kind: 'field';
+    key: string;
+    value: string;
+} | {
+    kind: 'compare';
+    key: string;
+    op: QueryComparator;
+    value: string;
+} | {
+    kind: 'relative';
+    key: 'updated_at';
+    direction: 'newer' | 'older';
+    ms: number;
+};
+export type ParsedQuery = {
+    terms: string[];
+    filters: QueryFilter[];
+};
+export type SuccessEnvelope<T> = {
+    ok: true;
+    action: string;
+    file: string;
+    result: T;
+    warnings: string[];
+};
+export type ErrorEnvelope = {
+    ok: false;
+    action: string;
+    error: {
+        code: ErrorCode | 'UNKNOWN';
+        message: string;
+        hint?: string;
+    };
+};

package/dist/types.js

@@ -0,0 +1,8 @@
+export const ROOT_ID = 'root';
+export const RESERVED_FIELDS = new Set([
+    'id',
+    'parent',
+    'children',
+    'created_at',
+    'updated_at'
+]);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@yinzuoweia/nis",
+  "version": "0.1.0",
+  "description": "NIS CLI for agent-friendly JSON tree operations",
+  "type": "module",
+  "bin": {
+    "nis": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "execa": "^9.6.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}