@assethub/cli 0.1.33 → 0.1.36

package/dist/updateNotice.d.ts

@@ -0,0 +1,71 @@
+import { type UpdateDeps } from './update.js';
+export declare const CHECK_INTERVAL_MS: number;
+export declare const REFRESH_CHILD_ENV = "ASSETHUB_UPDATE_REFRESH_CHILD";
+/** What the last background install did; announced once, then marked. */
+export type AutoUpdateResult = {
+    from: string;
+    to: string;
+    at: string;
+    announced?: boolean;
+} | {
+    from: string;
+    error: string;
+    at: string;
+    announced?: boolean;
+};
+export type UpdateCheckCache = {
+    checkedAt: string;
+    latest: string;
+    autoUpdate?: AutoUpdateResult;
+    /** When the `is available` line was last shown: at most once a day. */
+    noticedAt?: string;
+};
+export declare const updateCheckPath: (configPath: string) => string;
+export declare const readUpdateCheck: (path: string) => Promise<UpdateCheckCache | undefined>;
+export declare const writeUpdateCheck: (path: string, latest: string, now?: Date, autoUpdate?: AutoUpdateResult) => Promise<void>;
+/** Rewrites the cache with some fields changed (announcement bookkeeping by the foreground command). */
+export declare const patchUpdateCheck: (path: string, cache: UpdateCheckCache, patch: Partial<UpdateCheckCache>) => Promise<void>;
+export declare const ATTEMPT_INTERVAL_MS: number;
+export declare const attemptPath: (cachePath: string) => string;
+/** Whether a refresh was started recently enough not to start another; records this attempt when not. */
+export declare const claimRefreshAttempt: (cachePath: string, now?: Date) => Promise<boolean>;
+export declare const settingsPath: (configPath: string) => string;
+/** The saved choice: true or false, or undefined when never set (which means on). */
+export declare const readAutoUpdateSetting: (path: string) => Promise<boolean | undefined>;
+export declare const writeAutoUpdateSetting: (path: string, autoUpdate: boolean) => Promise<void>;
+/** Auto-update is on by default; the saved setting or ASSETHUB_NO_AUTO_UPDATE turns it off. */
+export declare const autoUpdateEnabled: (setting: boolean | undefined, env: NodeJS.ProcessEnv) => boolean;
+/**
+ * Only a global install can be upgraded by `assethub update`: a project
+ * dependency, an npx run or a source checkout has nothing to announce. Same
+ * layouts as update.ts's detectInstall, without running `npm root --global`
+ * on every command.
+ */
+export declare const isInstalledPackage: (cliPath: string) => boolean;
+/** Opted out, or running somewhere nobody reads a hint (CI). */
+export declare const updateCheckDisabled: (env: NodeJS.ProcessEnv) => boolean;
+export type NoticeDecision = {
+    notices: string[];
+    refresh: boolean;
+    markAnnounced: boolean;
+    markNoticed: boolean;
+};
+/** What to print now, whether to mark a background install as announced, and whether to refresh. */
+export declare const decideUpdateNotice: (current: string, cache: UpdateCheckCache | undefined, now: Date) => NoticeDecision;
+/** One install at a time, background or `assethub update`: a second one leaves it alone. */
+export declare const takeLock: (path: string) => Promise<boolean>;
+/**
+ * Reads the latest version and, when auto-update is on and it is newer,
+ * installs it through `runUpdate` (same installer, same login check as
+ * `assethub update --yes`). Records the outcome for the next command to announce.
+ */
+export declare const refreshUpdateCheck: (input: {
+    cachePath: string;
+    lockPath: string;
+    autoUpdate: boolean;
+    deps: UpdateDeps;
+    now?: () => Date;
+}) => Promise<UpdateCheckCache | undefined>;
+/** Starts the background refresh and returns at once; the child outlives this process. */
+export declare const refreshInBackground: (node: string, cli: string, configPath: string) => void;
+//# sourceMappingURL=updateNotice.d.ts.map

package/dist/updateNotice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateNotice.d.ts","sourceRoot":"","sources":["../src/updateNotice.ts"],"names":[],"mappings":"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"}

package/dist/updateNotice.js

@@ -0,0 +1,189 @@
+// Keeping the CLI current. Once a day a detached `assethub update --refresh-check`
+// process reads the latest version and, with auto-update on (the default),
+// installs it the way `assethub update` would. No command ever waits on the
+// network or the install: each one only reads the small cache file the
+// background process leaves behind, announces what happened once, and moves on.
+import { spawn } from 'node:child_process';
+import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { compareVersions, PACKAGE_NAME, runUpdate } from './update.js';
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const REFRESH_CHILD_ENV = 'ASSETHUB_UPDATE_REFRESH_CHILD';
+export const updateCheckPath = (configPath) => join(dirname(configPath), 'update-check.json');
+export const readUpdateCheck = async (path) => {
+    try {
+        const cache = JSON.parse(await readFile(path, 'utf8'));
+        return typeof cache.checkedAt === 'string' && typeof cache.latest === 'string'
+            ? {
+                checkedAt: cache.checkedAt,
+                latest: cache.latest,
+                ...(cache.autoUpdate && typeof cache.autoUpdate === 'object' ? { autoUpdate: cache.autoUpdate } : {}),
+                ...(typeof cache.noticedAt === 'string' ? { noticedAt: cache.noticedAt } : {}),
+            }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const writeUpdateCheck = async (path, latest, now = new Date(), autoUpdate) => {
+    await mkdir(dirname(path), { recursive: true });
+    const cache = { checkedAt: now.toISOString(), latest, ...(autoUpdate ? { autoUpdate } : {}) };
+    await writeFile(path, `${JSON.stringify(cache)}\n`);
+};
+/** Rewrites the cache with some fields changed (announcement bookkeeping by the foreground command). */
+export const patchUpdateCheck = async (path, cache, patch) => {
+    await writeFile(path, `${JSON.stringify({ ...cache, ...patch })}\n`);
+};
+// A failed or slow refresh leaves the cache stale; this marker keeps every
+// command from starting another one. Retried at most once an hour.
+export const ATTEMPT_INTERVAL_MS = 60 * 60 * 1000;
+export const attemptPath = (cachePath) => `${cachePath}.attempt`;
+/** Whether a refresh was started recently enough not to start another; records this attempt when not. */
+export const claimRefreshAttempt = async (cachePath, now = new Date()) => {
+    const path = attemptPath(cachePath);
+    const last = await readFile(path, 'utf8').then(text => Date.parse(text.trim()), () => Number.NaN);
+    if (Number.isFinite(last) && now.getTime() - last < ATTEMPT_INTERVAL_MS && last <= now.getTime())
+        return false;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${now.toISOString()}\n`);
+    return true;
+};
+// ---- the auto-update setting (on unless turned off) ----
+export const settingsPath = (configPath) => join(dirname(configPath), 'settings.json');
+/** The saved choice: true or false, or undefined when never set (which means on). */
+export const readAutoUpdateSetting = async (path) => {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8')).autoUpdate;
+        return typeof value === 'boolean' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const writeAutoUpdateSetting = async (path, autoUpdate) => {
+    let settings = {};
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            settings = parsed;
+    }
+    catch {
+        // missing or unreadable: start fresh
+    }
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ ...settings, autoUpdate }, null, 2)}\n`);
+};
+const truthy = (value) => ['1', 'true', 'yes'].includes((value ?? '').toLowerCase());
+/** Auto-update is on by default; the saved setting or ASSETHUB_NO_AUTO_UPDATE turns it off. */
+export const autoUpdateEnabled = (setting, env) => setting !== false && !truthy(env.ASSETHUB_NO_AUTO_UPDATE) && !updateCheckDisabled(env);
+/**
+ * Only a global install can be upgraded by `assethub update`: a project
+ * dependency, an npx run or a source checkout has nothing to announce. Same
+ * layouts as update.ts's detectInstall, without running `npm root --global`
+ * on every command.
+ */
+export const isInstalledPackage = (cliPath) => {
+    const path = cliPath.replaceAll('\\', '/');
+    if (!path.includes(`/node_modules/${PACKAGE_NAME}/`) || path.includes('/_npx/'))
+        return false;
+    return [
+        `/lib/node_modules/${PACKAGE_NAME}/`, // npm, nvm, Homebrew node, a custom npm prefix
+        `/npm/node_modules/${PACKAGE_NAME}/`, // npm on Windows (%AppData%/npm)
+        '/.volta/',
+        '/.bun/install/global/',
+        '/pnpm/global/',
+        '/yarn/global/',
+    ].some(segment => path.includes(segment));
+};
+/** Opted out, or running somewhere nobody reads a hint (CI). */
+export const updateCheckDisabled = (env) => truthy(env.ASSETHUB_NO_UPDATE_CHECK) || Boolean(env.CI);
+const TURN_OFF = 'turn off with `assethub setup --no-auto-update`';
+/** What to print now, whether to mark a background install as announced, and whether to refresh. */
+export const decideUpdateNotice = (current, cache, now) => {
+    const checked = cache ? Date.parse(cache.checkedAt) : Number.NaN;
+    const refresh = !Number.isFinite(checked) || now.getTime() - checked >= CHECK_INTERVAL_MS || checked > now.getTime();
+    const notices = [];
+    const result = cache?.autoUpdate;
+    const announce = result !== undefined && !result.announced;
+    if (announce && 'to' in result && result.to === current)
+        notices.push(`${PACKAGE_NAME} updated itself from ${result.from} to ${result.to} (auto-update; ${TURN_OFF}).`);
+    if (announce && 'error' in result)
+        notices.push(`${PACKAGE_NAME} could not update itself to ${cache?.latest}: ${result.error}`);
+    const noticed = cache?.noticedAt ? Date.parse(cache.noticedAt) : Number.NaN;
+    const noticeDue = !Number.isFinite(noticed) || now.getTime() - noticed >= CHECK_INTERVAL_MS || noticed > now.getTime();
+    // A failed install is reported together with the release it could not install.
+    const available = cache !== undefined && compareVersions(cache.latest, current) > 0 && (noticeDue || (announce && 'error' in result));
+    if (available)
+        notices.push(`${PACKAGE_NAME} ${cache.latest} is available (you have ${current}). Run \`assethub update\` to upgrade; your login is kept.`);
+    return { notices, refresh, markAnnounced: announce, markNoticed: available };
+};
+// ---- the background refresh ----
+const LOCK_STALE_MS = 15 * 60 * 1000;
+/** One install at a time, background or `assethub update`: a second one leaves it alone. */
+export const takeLock = async (path) => {
+    await mkdir(dirname(path), { recursive: true });
+    try {
+        await (await open(path, 'wx')).close();
+        return true;
+    }
+    catch {
+        const age = await stat(path).then(info => Date.now() - info.mtimeMs, () => 0);
+        if (age < LOCK_STALE_MS)
+            return false;
+        await rm(path, { force: true });
+        try {
+            await (await open(path, 'wx')).close();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+};
+/**
+ * Reads the latest version and, when auto-update is on and it is newer,
+ * installs it through `runUpdate` (same installer, same login check as
+ * `assethub update --yes`). Records the outcome for the next command to announce.
+ */
+export const refreshUpdateCheck = async (input) => {
+    const now = input.now ?? (() => new Date());
+    if (!(await takeLock(input.lockPath)))
+        return undefined;
+    try {
+        const [current, latest] = await Promise.all([input.deps.currentVersion(), input.deps.latestVersion()]);
+        let autoUpdate;
+        if (input.autoUpdate && compareVersions(latest, current) > 0) {
+            try {
+                const report = await runUpdate({ yes: true }, { ...input.deps, latestVersion: async () => latest, interactive: false });
+                if (report.status === 'updated')
+                    autoUpdate = { from: report.from, to: report.to, at: now().toISOString() };
+            }
+            catch (error) {
+                autoUpdate = { from: current, error: error instanceof Error ? error.message : String(error), at: now().toISOString() };
+            }
+        }
+        await writeUpdateCheck(input.cachePath, latest, now(), autoUpdate);
+        return { checkedAt: now().toISOString(), latest, ...(autoUpdate ? { autoUpdate } : {}) };
+    }
+    finally {
+        await rm(input.lockPath, { force: true });
+    }
+};
+/** Starts the background refresh and returns at once; the child outlives this process. */
+export const refreshInBackground = (node, cli, configPath) => {
+    try {
+        const child = spawn(node, [cli, 'update', '--refresh-check', '--config', configPath], {
+            detached: true,
+            stdio: 'ignore',
+            // Marks the child (and the `assethub doctor` it runs to verify an install) so it
+            // neither prints notices nor starts another refresh.
+            env: { ...process.env, [REFRESH_CHILD_ENV]: '1' },
+        });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // best effort: a missing hint must never fail the user's command
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assethub/cli",
-  "version": "0.1.33",
+  "version": "0.1.36",
   "description": "Command line interface for AssetHub.",
   "type": "module",
   "bin": {

package/skills/assethub/SKILL.md

@@ -12,7 +12,7 @@ description: |
   - Recording whether a generated asset is acceptable
 
   DO NOT TRIGGER for:
-  - Installing or configuring the CLI (use `assethub init`, `assethub auth login`)
+  - Installing or configuring the CLI (use `assethub setup`, `assethub doctor --setup`)
   - Managing workspace members (use `assethub workspace ...`)
 ---
 
@@ -31,6 +31,23 @@ description: |
 
 Always in this order. Skipping a step is how credits get wasted.
 
+### 0. Make sure the CLI is current (once per session)
+
+```bash
+assethub update --check
+```
+
+Operations, models and these rules change between releases, and an old CLI can reject flags the server now expects or miss a safety fix. Run this once at the start of a session, before the first paid call. It is free.
+
+Auto-update is on by default: once a day the CLI installs a newer release by itself in the background, and the next command says so on stderr (`updated itself from … to …`). So this check usually reports `up_to_date`. It is still needed: auto-update may be off (`assethub setup --no-auto-update`, `ASSETHUB_NO_AUTO_UPDATE=1`, CI), may have failed, or may not have run yet today.
+
+- `"status": "up_to_date"`: carry on.
+- `"status": "update_available"`: run `assethub update --yes`. It upgrades the global install with the package manager that installed it and keeps the saved login. Tell the user which version you moved from and to (`from`, `to`). The next `assethub` command refreshes this skill automatically, so re-read it after that command; its rules may have changed.
+- `update` refuses (an `npx` or project-local install, or a source checkout) or fails (no network): continue on the current version and tell the user once. Do not retry it in a loop.
+- Do not update while another `assethub` command is still running (a `--wait` in another terminal). Runs on the server are not affected by an update; resume them afterwards with their `runId`.
+
+The CLI also prints a one-line `is available` or `could not update itself` notice on stderr. Treat it the same way. When you see `updated itself`, re-read this skill after that command, as above. Never turn auto-update off for the user.
+
 ### 1. Check what this key can do
 
 ```bash
@@ -115,7 +132,7 @@ assethub evaluations submit --canvas <canvas-id> --artifact <asset-id> \
 
 - `production run` defaults to `full_auto`, which never pauses for a human. **Always pass `--max-cost-credits <n>`.** The server caps `--max-iterations` at 5.
 - Over MCP the same rule applies: always set `maxCostCredits` on `production_run`.
-- `assethub account get` shows the balance. Check it before a batch.
+- Before a batch, run `production run --image <file> --estimate` to see the cost. The CLI has no balance command; find the credit routes with `assethub api search credit`.
 - Prefer a dedicated, scoped API key for agent work rather than a full-access one.
 
 ## Rules learned the hard way
@@ -124,7 +141,7 @@ assethub evaluations submit --canvas <canvas-id> --artifact <asset-id> \
 - Part extractor names are the public product names: `V1.5`, `V2.0 alpha`, `V2.1 alpha`. Internal IDs are not accepted.
 - `parts split` and `parts compare` with `--preprocess-prompt` create a second production order; use `--all-ready`, not `--task-id`.
 - Every generation should land on a canvas. Pass `--canvas <id>` to keep a job's steps together; without it the CLI makes one canvas per working directory. `assethub canvas open <id>` shows the user what happened.
-- A complaint like "the mesh has extra limbs" is usually an input problem: stray lines, shadows, or inconsistent views. Clean the image (`image edit`) before switching models.
+- A complaint like "the mesh has extra limbs" is usually an input problem: stray lines, shadows, or inconsistent views. Clean the image before switching models: `image generate --file <image> --prompt "remove stray lines and shadows, plain background"`, or `parts compare --preprocess-prompt <text>`.
 - Input can come from a file, a URL, stdin bytes, base64, a data URI, an OpenAI- or Anthropic-style JSON attachment (`--stdin-json`), or the clipboard. You never need to write a temporary file first.
 - Large or complex requests: `--input-json @request.json` with the schema from `api describe`.