image-skill 0.1.6 → 0.1.7

package/README.md

@@ -11,7 +11,14 @@ Install the agent skill from the public mirror repo:
 npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
 ```
 
-Install the executable CLI from npm:
+Run the executable CLI from npm without requiring a writable global npm prefix:
+
+```bash
+npm exec --yes --package image-skill@latest -- image-skill doctor --json
+```
+
+For repeated shell use, global install is optional only after confirming the
+runtime has a writable npm prefix:
 
 ```bash
 npm install -g image-skill
@@ -37,3 +44,13 @@ The CLI saves hosted agent tokens only when `--save` is explicit. Saved tokens
 live at `${XDG_CONFIG_HOME:-~/.config}/image-skill/config.json` by default with
 0600 permissions. Use `IMAGE_SKILL_CONFIG_PATH` to override the config path and
 `IMAGE_SKILL_TOKEN` or `--token-stdin` for runtime secret injection.
+
+Fresh sandboxes should prefer:
+
+```bash
+export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
+npm exec --yes --package image-skill@latest -- image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name creative-agent --runtime openclaw --save --json
+```
+
+If npm prefix/cache paths are read-only, set `npm_config_cache` and
+`npm_config_prefix` to writable directories before using `npm exec`.

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.6";
+const VERSION = "0.1.7";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_CONFIG_PATH = join(
   process.env.XDG_CONFIG_HOME ?? join(os.homedir(), ".config"),
@@ -79,37 +79,37 @@ async function main(rawArgv) {
   try {
     switch (command) {
       case "doctor":
-        return doctor(rest);
+        return await doctor(rest);
       case "signup":
-        return signup(rest);
+        return await signup(rest);
       case "auth":
-        return auth(rest);
+        return await auth(rest);
       case "whoami":
-        return whoami(rest);
+        return await whoami(rest);
       case "usage":
-        return usage(rest);
+        return await usage(rest);
       case "quota":
-        return quota(rest);
+        return await quota(rest);
       case "credits":
-        return credits(rest);
+        return await credits(rest);
       case "models":
-        return models(rest);
+        return await models(rest);
       case "capabilities":
-        return capabilities(rest);
+        return await capabilities(rest);
       case "create":
-        return create(rest);
+        return await create(rest);
       case "upload":
-        return upload(rest);
+        return await upload(rest);
       case "edit":
-        return edit(rest);
+        return await edit(rest);
       case "assets":
-        return assets(rest);
+        return await assets(rest);
       case "jobs":
-        return jobs(rest);
+        return await jobs(rest);
       case "activity":
-        return activity(rest);
+        return await activity(rest);
       case "feedback":
-        return feedback(rest);
+        return await feedback(rest);
       default:
         return failure(
           `image-skill ${command}`,
@@ -209,6 +209,12 @@ async function signup(argv) {
   }
   const save = flagBool(args, "save");
   const showToken = flagBool(args, "show-token");
+  if (save) {
+    const configReady = await assertConfigWritable("image-skill signup");
+    if (!configReady.ok) {
+      return configReady.result;
+    }
+  }
   const result = await apiRequest({
     command: "image-skill signup",
     method: "POST",
@@ -238,12 +244,16 @@ async function signup(argv) {
         },
       );
     }
-    await saveConfig({
-      api_base_url: apiBase(args),
-      token,
-      saved_at: new Date().toISOString(),
-      actor: result.envelope.actor ?? result.envelope.data?.actor ?? null,
-    });
+    try {
+      await saveConfig({
+        api_base_url: apiBase(args),
+        token,
+        saved_at: new Date().toISOString(),
+        actor: result.envelope.actor ?? result.envelope.data?.actor ?? null,
+      });
+    } catch (error) {
+      return configWriteFailure("image-skill signup", error);
+    }
     warnings.push(`saved hosted token to ${configPath()}`);
   }
 
@@ -302,12 +312,20 @@ async function auth(argv) {
     if (!token.ok) {
       return token.result;
     }
-    await saveConfig({
-      api_base_url: apiBase(args),
-      token: token.token,
-      saved_at: new Date().toISOString(),
-      actor: null,
-    });
+    const configReady = await assertConfigWritable("image-skill auth save");
+    if (!configReady.ok) {
+      return configReady.result;
+    }
+    try {
+      await saveConfig({
+        api_base_url: apiBase(args),
+        token: token.token,
+        saved_at: new Date().toISOString(),
+        actor: null,
+      });
+    } catch (error) {
+      return configWriteFailure("image-skill auth save", error);
+    }
     return success("image-skill auth save", {
       saved: true,
       config_path: configPath(),
@@ -1256,6 +1274,43 @@ async function saveConfig(value) {
   await chmod(path, 0o600);
 }
 
+async function assertConfigWritable(command) {
+  const path = configPath();
+  const probePath = `${path}.write-test-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(probePath, "", { mode: 0o600 });
+    await chmod(probePath, 0o600);
+    await rm(probePath, { force: true });
+    return { ok: true };
+  } catch (error) {
+    await rm(probePath, { force: true }).catch(() => {});
+    return {
+      ok: false,
+      result: configWriteFailure(command, error),
+    };
+  }
+}
+
+function configWriteFailure(command, error) {
+  const message =
+    error instanceof Error
+      ? error.message
+      : "public CLI could not write its local auth config";
+  return failure(
+    command,
+    9,
+    "PUBLIC_CLI_CONFIG_WRITE_FAILED",
+    `public CLI could not write auth config at ${configPath()}: ${message}`,
+    true,
+    {
+      suggested_command:
+        'IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json" image-skill signup --agent --agent-contact CONTACT_OR_SPONSOR_INBOX --agent-name NAME --runtime RUNTIME --save --json',
+      docs_url: "https://image-skill.com/cli.md#local-config-and-install",
+    },
+  );
+}
+
 function parseArgs(argv) {
   const flags = new Map();
   const positionals = [];

package/cli.md

@@ -92,6 +92,44 @@ printf '%s\n' "$IMAGE_SKILL_TOKEN" | image-skill usage quota --token-stdin --jso
 `--api-base-url` is an advanced preview/test override; production public agents
 should omit it.
 
+### Local Config And Install
+
+Prefer package execution in fresh agent sandboxes:
+
+```bash
+npm exec --yes --package image-skill@latest -- image-skill doctor --json
+```
+
+Global install is optional, not the primary path. If `npm install -g image-skill`
+or `npx image-skill@latest ...` hits prefix/cache `EACCES`, retry with writable
+package-manager paths instead of cloning private source:
+
+```bash
+export npm_config_cache="${npm_config_cache:-$PWD/.npm-cache}"
+export npm_config_prefix="${npm_config_prefix:-$PWD/.npm-global}"
+export PATH="$npm_config_prefix/bin:$PATH"
+npm exec --yes --package image-skill@latest -- image-skill doctor --json
+```
+
+Saved auth state defaults to
+`${XDG_CONFIG_HOME:-~/.config}/image-skill/config.json`. If that location is
+read-only, set a writable config path before `signup --save`:
+
+```bash
+export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
+npm exec --yes --package image-skill@latest -- image-skill signup --agent \
+  --agent-contact agent-ops@example.com \
+  --agent-name creative-agent \
+  --runtime codex \
+  --save \
+  --json
+```
+
+Config write failures return `PUBLIC_CLI_CONFIG_WRITE_FAILED` with a structured
+`error.recovery.suggested_command`. Agents should follow that recovery field,
+then continue with `whoami`, `usage quota`, `models list`, and the requested
+creative flow.
+
 ### `image-skill whoami`
 
 Shows current actor, organization, claim state, token class, and grants.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Thin hosted CLI for Image Skill, a creative runtime for agents.",
   "type": "module",
   "private": false,

package/skill.md

@@ -35,12 +35,18 @@ supports skills.sh-compatible installation:
 npx skills add danielgwilson/image-skill-cli --skill image-skill -g -a codex -y
 ```
 
-Install the executable CLI from npm:
+Run the executable CLI from npm without relying on a writable global npm
+prefix:
 
 ```bash
-npm install -g image-skill
+npm exec --yes --package image-skill@latest -- image-skill doctor --json
 ```
 
+For repeated shell use, use global package linking only after confirming the
+runtime has a writable npm prefix. In fresh sandboxes, prefer `npm exec`/`npx` and set
+`IMAGE_SKILL_CONFIG_PATH` to a writable persistent path if the default config
+home is read-only.
+
 Check service and client health:
 
 ```bash
@@ -75,6 +81,27 @@ If the runtime supports stdin secret handoff, prefer `--token-stdin` for
 `whoami`, `usage quota`, `quota`, `create`, and `feedback create` instead of
 placing the token in command args.
 
+## Local Config And Install
+
+The CLI stores saved hosted tokens only when `--save` is explicit. By default
+that file lives at `${XDG_CONFIG_HOME:-~/.config}/image-skill/config.json` with
+0600 permissions. If a sandbox or hosted executor has a read-only home or npm
+prefix, keep using the public package through `npm exec` and point auth state at
+a writable path:
+
+```bash
+export IMAGE_SKILL_CONFIG_PATH="$PWD/.image-skill/config.json"
+npm exec --yes --package image-skill@latest -- image-skill signup --agent \
+  --agent-contact CONTACT_OR_SPONSOR_INBOX \
+  --agent-name AGENT_NAME \
+  --runtime RUNTIME_NAME \
+  --save \
+  --json
+```
+
+Do not clone private source or fall back to direct provider APIs because global
+package linking or the default config directory is blocked.
+
 Inspect identity and quota:
 
 ```bash