@yuchaocheng/yusijia 0.1.0-beta.1

package/dist/storage.js

@@ -0,0 +1,139 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import { dirname, join, resolve, parse } from 'node:path';
+import { homedir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { CliError, normalizeSite } from './core.js';
+export const configDir = () => join(homedir(), '.config', 'yusijia');
+export const MAX_PRIVATE_JSON_BYTES = 32 * 1024 * 1024;
+function checkPrivateBytes(bytes) {
+    if (bytes > MAX_PRIVATE_JSON_BYTES)
+        throw new CliError('LOCAL_STATE_TOO_LARGE');
+}
+export function serializePrivateJson(value) {
+    const text = `${JSON.stringify(value, null, 2)}\n`;
+    checkPrivateBytes(Buffer.byteLength(text, 'utf8'));
+    return text;
+}
+const missing = (e) => e.code === 'ENOENT';
+export async function checkParents(file) {
+    const absolute = resolve(file);
+    let current = parse(absolute).root;
+    for (const part of absolute.slice(current.length).split('/').filter(Boolean)) {
+        current = join(current, part);
+        try {
+            if ((await lstat(current)).isSymbolicLink())
+                throw new CliError('UNSAFE_PATH');
+        }
+        catch (e) {
+            if (!missing(e))
+                throw e;
+        }
+    }
+}
+function checkOwner(s, mode) {
+    if (s.uid !== process.getuid?.() || (mode !== undefined && (s.mode & 0o777) !== mode))
+        throw new CliError('UNSAFE_PATH');
+}
+export async function privateDirectory(dir) {
+    await checkParents(dir);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const s = await lstat(dir);
+    if (!s.isDirectory() || s.isSymbolicLink())
+        throw new CliError('UNSAFE_PATH');
+    checkOwner(s, 0o700);
+}
+export async function readPrivateJson(file) {
+    await checkParents(file);
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const s = await handle.stat();
+        checkOwner(s, 0o600);
+        if (!s.isFile())
+            throw new CliError('UNSAFE_PATH');
+        checkPrivateBytes(s.size);
+        const text = await handle.readFile('utf8');
+        checkPrivateBytes(Buffer.byteLength(text, 'utf8'));
+        return JSON.parse(text);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readInputJson(file) {
+    await checkParents(file);
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const s = await handle.stat();
+        if (!s.isFile() || s.size > MAX_PRIVATE_JSON_BYTES)
+            throw new CliError('PAYLOAD_TOO_LARGE');
+        return JSON.parse(await handle.readFile('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function writePrivateText(file, text) {
+    checkPrivateBytes(Buffer.byteLength(text, 'utf8'));
+    await checkParents(file);
+    const parent = dirname(resolve(file));
+    const ps = await lstat(parent);
+    checkOwner(ps);
+    if (!ps.isDirectory() || (ps.mode & 0o022))
+        throw new CliError('UNSAFE_PATH');
+    try {
+        const s = await lstat(file);
+        if (!s.isFile())
+            throw new CliError('UNSAFE_PATH');
+        checkOwner(s, 0o600);
+    }
+    catch (e) {
+        if (!missing(e))
+            throw e;
+    }
+    const temp = join(parent, `.${randomUUID()}.tmp`);
+    const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(text);
+        await handle.sync();
+        await handle.close();
+        await checkParents(file);
+        await rename(temp, file);
+    }
+    finally {
+        await handle.close().catch(() => { });
+        await unlink(temp).catch(() => { });
+    }
+}
+export async function writePrivateJson(file, value) { return writePrivateText(file, serializePrivateJson(value)); }
+const credentialSchema = z.object({ token: z.string().min(1), expiresAt: z.iso.datetime(), userId: z.string().min(1) }).strict();
+const credentialsSchema = z.record(z.string(), credentialSchema);
+export class CredentialStore {
+    directory;
+    constructor(directory = configDir()) {
+        this.directory = directory;
+    }
+    async read() {
+        await privateDirectory(this.directory);
+        try {
+            return credentialsSchema.parse(await readPrivateJson(join(this.directory, 'credentials.json')));
+        }
+        catch (e) {
+            if (missing(e))
+                return {};
+            throw e;
+        }
+    }
+    async get(site) { return (await this.read())[normalizeSite(site)]; }
+    async set(site, credential) {
+        const all = await this.read();
+        all[normalizeSite(site)] = credentialSchema.parse(credential);
+        await writePrivateJson(join(this.directory, 'credentials.json'), all);
+    }
+    async remove(site) {
+        const all = await this.read();
+        delete all[normalizeSite(site)];
+        await writePrivateJson(join(this.directory, 'credentials.json'), all);
+    }
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@yuchaocheng/yusijia",
+  "version": "0.1.0-beta.1",
+  "description": "Family content CLI and Agent Skill for photos, albums, timelines and diaries",
+  "license": "UNLICENSED",
+  "publishConfig": { "access": "public", "tag": "beta", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "bin": { "yusijia": "dist/cli.js" },
+  "engines": { "node": ">=20.20.2" },
+  "os": ["darwin"],
+  "cpu": ["arm64", "x64"],
+  "files": ["dist", "skills", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit --noUnusedLocals --noUnusedParameters",
+    "test": "vitest run --config vitest.config.ts",
+    "test:package": "node scripts/package-test.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": { "exifr": "^7.1.3", "zod": "^4.3.6" },
+  "devDependencies": { "@types/node": "^20", "typescript": "^5", "vitest": "^4.1.2" }
+}

package/skills/family-content/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: family-content
+description: Use yusijia to prepare explicitly supplied photos and query or propose confirmed family albums, growth timeline events and diary changes.
+metadata:
+  cli-version: '{{CLI_VERSION}}'
+---
+
+# Family Content
+
+Use the installed `yusijia` command. Do not import website code, access a database,
+read credentials.json, request passwords/tokens, or copy browser cookies. This Skill
+contains instructions, not family data. Check `yusijia --version` and `yusijia --help`.
+The installed Skill and CLI should have the same version.
+
+## Identity
+
+`yusijia auth login --json` opens the site's authorization page. The user signs in
+and approves there. `auth status --json` shows the bound account and expiry. Default
+site is https://yusijia.me; use explicit `--site` for a different HTTPS site or local
+development loopback. State the site/account before any content plan. `auth logout`
+revokes then removes this site's credential. A failure is not successful revocation.
+The credential lasts 30 days and is plaintext in an owner-only file, not encrypted;
+same-user processes, root and copied files remain a risk.
+
+## Read And Prepare
+
+- Query only relevant bounded pages: `photos|albums|timeline|diary list --limit 30
+  --cursor <opaque-cursor> --json`; `get --id <id> --json` for detail.
+- Photo URLs are omitted by default. Only request `photos get --id <id>
+  --include-url --json` when needed to inspect an image; do not broadly print, share,
+  or retain signed URLs in plans, progress or long-lived documents.
+- Scan only paths supplied by the user: `photos scan --input <directory-or-zip>
+  --out <scan.json> --json`, or repeat `--files <file>` for an explicit set.
+- Show unsupported, corrupt, oversized and duplicate reports. HEIC must be converted
+  first. Do not imply rule-based grouping is visual inspection, or that old photos
+  without hashes can all be deduplicated. Never scan the whole disk or call external
+  vision services by default. Keep generated plans/scans private.
+
+## Preview, Confirm, Execute
+
+Business commands only generate local plans. They do not upload or save drafts.
+Build proposals with `albums create/update/add/remove`, `timeline create/update`,
+`diary create/edit/publish`, `photos import/cancel`, or combine typed actions using
+`plan --input <draft.json> --out <plan.json>`. Use `plan show --plan <plan.json> --json`.
+Read `yusijia --help` and the package README for payload examples.
+
+To import and associate photos under one confirmation, put `photos.import` before
+`albums.photos` in the same plan and use photo references in its `add` array:
+`{ref: "<import-operation-uuid>", field: "photoId", localCandidateId: "<selected-candidate>"}`.
+References resolve only after the prior import succeeds; never invent a photo ID.
+In a combined plan, `albums.photos` requires both `payload.add` and
+`payload.remove`, even when one is empty: `{ "add": [<photo reference>],
+"remove": [] }`. Include the album `target` and its `expectedVersion` (literal
+values or references to a prior album action). For a standalone association,
+prefer `albums add/remove --id ... --photo-id ... --out ...`.
+
+Before execution show the site, account, every target and expected version, selected
+photos including GPS/time and create/reuse expectations, album associations, event
+date/title/description/photos, and complete diary text plus DRAFT/PUBLISHED status.
+Ask the user to confirm that exact plan. One explicit confirmation may cover the
+whole plan. A saved draft is also a remote write requiring confirmation.
+
+Only after confirmation run `execute --plan <plan.json> --confirm-hash <planHash>
+--json`. Never supply this flag before consent or treat possession of a hash as proof
+of human intent. Changes to content, target, version or source bytes invalidate the
+old confirmation. Use `plan --previous <old-plan.json> --input <revised.json> --out
+<new-plan.json>` for edits: changed unsent actions get new IDs. Completed or uncertain
+actions must not be rewritten; use new explicit update actions after resolving them.
+
+Diary create blocks are `{type,text,level?}`, not raw BlockNote JSON. Editing is
+`replaceText` by blockId, `append` typed text blocks, or an explicit status change.
+Never flatten an existing rich document or remove images/tables without consent.
+Unsupported edits must stop and leave the website editor as the alternative.
+Timeline allows at most three photos. Album remove only removes associations.
+
+## Recovery
+
+Partial completion is a nonzero exit, not an all-or-nothing rollback. Report each
+success and its ID, each failed/unknown item and skipped dependency. Preserve the
+plan, progress and operation IDs. Resume using the same `execute` command, or
+`photos resume --plan ... --confirm-hash ...`; receipt lookup precedes replay of
+uncertain requests. A 404 receipt does not prove nothing committed. Do not change
+IDs or silently reduce selection to bypass a failure. Publishing starts only after
+all selected candidates are verified. Cancellation is a separate confirmed plan;
+already published photos remain. Do not delete formal content as compensation.
+
+## Installation And Updates
+
+`skills install [--dir <exact-skill-directory>]` defaults to
+`~/.agents/skills/family-content`; it does not configure the host or other Skills.
+`skills update` synchronizes registered installations without overwriting edits.
+`update` uses public npm for this global package, then the new CLI synchronizes
+Skills. Do not run sudo, read secret files, or claim success on a Skill conflict.
+The private placeholder package cannot update remotely until publication preflight.