@docyrus/animaguru 0.38.0 → 0.39.0

package/README.md

@@ -25,6 +25,8 @@ animaguru auth status
 animaguru credits
 ```
 
+Signing in, and the commands that work with your account, need a plan on it; every account starts with a 7-day Individual Starter trial (see [Plan requirement](#plan-requirement)).
+
 The npm package requires Node.js 24+. Its default registry is https://registry.npmjs.org/. The package has no runtime npm dependencies; third-party notices are included.
 
 From this repository, `npm ci && npm run cli:build` builds the CLI and `npm run cli -- --help` runs it. `npm run cli:release` prepares the npm tarball and public Mac downloads. `npm run cli:publish` publishes that reviewed release under the Docyrus organization; publishing requires a logged-in npm account with organization access and any required 2FA. Each release needs a new version in `cli/package.json`; the CLI version is read from that file. `npm run deploy` builds release downloads before uploading the site.
@@ -123,7 +125,19 @@ The catalog is an [Agent Skills discovery](https://agentskills.io) index at `htt
 
 ## Authentication and server
 
-The default server is https://animaguru.com. Use `--url http://localhost:5190` on the leaf command or `ANIMAGURU_URL` to override it. HTTP is allowed only for loopback development. Authentication is stored separately per server in `~/.config/animaguru/credentials.json`, with file permissions 0600. Set `ANIMAGURU_CONFIG_DIR` for an isolated configuration directory. Browser login uses a ten-minute, single-use device code and receives a seven-day revocable Better Auth session. `auth login --no-browser` prints the URL for manual use. `auth logout` revokes the token. `ANIMAGURU_TOKEN` supports secret injection by agent runners; do not put tokens in arguments or commit them.
+The default server is https://animaguru.com. Use `--url http://localhost:5190` on the leaf command or `ANIMAGURU_URL` to override it. HTTP is allowed only for loopback development. Authentication is stored separately per server in `~/.config/animaguru/credentials.json`, with file permissions 0600. Set `ANIMAGURU_CONFIG_DIR` for an isolated configuration directory. Browser login uses a ten-minute, single-use device code and receives a seven-day revocable Better Auth session. `auth login --no-browser` prints the URL for manual use. `auth logout` revokes the token. `ANIMAGURU_TOKEN` supports secret injection by agent runners; do not put tokens in arguments or commit them. Every request sends `User-Agent: animaguru-cli/<version>`, which the server uses to tell the CLI's sessions from the mobile apps'.
+
+### Plan requirement
+
+The CLI needs a plan on your account: Individual Starter, Individual Pro or Team. Every account starts with a 7-day Individual Starter trial when its email address is verified, with no card, and members of a team whose owner is on the Team plan are covered by the team. Staff accounts always have access.
+
+Without one:
+
+- `auth login` stops in the browser, which says the CLI needs a plan, and the device code then expires. Choose a plan first, then run `auth login` again.
+- Every command that calls the API, `animaguru curl` included, fails with HTTP 403 and code `plan_required`. The message gives the date your trial ended and the link to choose a plan, https://animaguru.com/app/billing. Retrying won't help: choose a plan, then run the command again. The browser studio keeps working with your credits meanwhile.
+- `auth status` still works. It prints `user`, `plan` (`free` is no plan; during the trial it is `starter` with `trial.endsAt`, in milliseconds) and `agents`: `allowed`, `via` (`staff`, `plan`, `trial` or `team`) and `trialEndedAt`.
+
+Local scaffolding such as `create` needs no sign-in or plan. The same rule applies to AnimaGuru's MCP server in Claude, Codex and ChatGPT.
 
 ## Call the API directly
 
@@ -672,7 +686,7 @@ MCP provides `list_brands`, `get_brand`, `create_brand`, `research_brand`, `upda
 
 ## Asset library
 
-CLI 0.15.0 adds `animaguru library`. Pro and Team accounts (and members of a team on the Team plan) can search AnimaGuru's asset library: ready-made sprites with animation sheets, images, video clips, music, voice-over speech and sound effects. Search uses natural language and keywords together. Importing into a project or downloading spends no credits, so check the library before generating a common asset.
+CLI 0.15.0 adds `animaguru library`. Every plan (Individual Starter and its trial, Individual Pro and Team) and members of a team on the Team plan can search AnimaGuru's asset library: ready-made sprites with animation sheets, images, video clips, music, voice-over speech and sound effects. Search uses natural language and keywords together. Importing into a project or downloading spends no credits, so check the library before generating a common asset.
 
 ```sh
 animaguru library types                                   # types, counts, and whether this account has access
@@ -779,7 +793,7 @@ Only one YouTube command may run at a time. Normal cancellation releases its loc
 
 ## Cloud sync and versions
 
-CLI 0.11.0 adds `animaguru cloud` for Individual Pro and Team plans. It syncs a video workspace, or a standalone video project, with an AnimaGuru project's animations and keeps every version. Use it to continue on another computer, work with your team and return to earlier versions. The studio shows the synced films on the project's **Animations** tab, next to its assets and Animator drafts. Syncing a personal project needs your own Individual Pro or Team plan. A team's projects need the team owner's Team plan, and every member can then save and download their animations.
+CLI 0.11.0 adds `animaguru cloud` for Individual Starter (and its trial), Individual Pro and Team plans. It syncs a video workspace, or a standalone video project, with an AnimaGuru project's animations and keeps every version. Use it to continue on another computer, work with your team and return to earlier versions. The studio shows the synced films on the project's **Animations** tab, next to its assets and Animator drafts. Syncing a personal project needs your own Individual Starter, Individual Pro or Team plan, or the Starter trial. A team's projects need the team owner's Team plan, and every member can then save and download their animations.
 
 ```sh
 animaguru auth login
@@ -805,7 +819,7 @@ Run the commands anywhere inside the workspace; `--dir PATH` chooses another fol
 
 Each version is a Git commit in the project's own animations repository on Cloudflare Artifacts. Where a file is stored depends on its type, not its size:
 
-- **Media** (images except SVG, video, audio and ZIP bundles) is uploaded once by SHA-256 at any size, however many versions use it, and Git keeps a small pointer. Media counts toward the plan's media storage: 20 GB for Individual Pro and 100 GB for each team.
+- **Media** (images except SVG, video, audio and ZIP bundles) is uploaded once by SHA-256 at any size, however many versions use it, and Git keeps a small pointer. Media counts toward the plan's media storage: 5 GB for Individual Starter, 20 GB for Individual Pro and 100 GB for each team.
 - **Work files** (code, configs, briefs, JSON, SVG, fonts and everything else) are stored in Git at any size up to Artifacts' 32 MB per-file limit. A larger work file stops the push and is named; add it to `.animaguruignore` or move it.
 
 The sync store lives in `.animaguru/sync/`, separate from any Git repository you keep for the folder, and linking adds it to `.gitignore`. Git credentials are short-lived and repository-scoped.
@@ -817,7 +831,7 @@ The sync store lives in `.animaguru/sync/`, separate from any Git repository you
 
 `restore` makes the folder, or the `--path` files and folders, match an earlier version without rewriting history. Push afterwards to save the result as the newest version. Replacing unsaved changes requires `--yes` and keeps backups.
 
-Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a plan ends, synced animations stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. `cloud unlink` stops syncing a folder without touching the cloud. `cloud delete PROJECT_ID --yes` deletes the project's animations with all their versions, Animator drafts and stored files; the project and its assets stay. A project's **Animations** tab in the studio lists its films, versions and their files, with downloads.
+Cloud files are never written into ignored or secret paths, through links, or outside the folder. If a workspace's plan ends, synced animations stay readable: list, versions, pull, clone and download still work, but pushing waits until the plan is active again. The CLI itself needs a plan on your own account (see [Plan requirement](#plan-requirement)); without one, the project's **Animations** tab in the studio still lists and downloads them. `cloud unlink` stops syncing a folder without touching the cloud. `cloud delete PROJECT_ID --yes` deletes the project's animations with all their versions, Animator drafts and stored files; the project and its assets stay. A project's **Animations** tab in the studio lists its films, versions and their files, with downloads.
 
 ## One brand, many animations
 

package/dist/animaguru.js

@@ -19761,7 +19761,7 @@ var require_ignore2 = __commonJS({
 // cli/package.json
 var package_default = {
   name: "@docyrus/animaguru",
-  version: "0.38.0",
+  version: "0.39.0",
   description: "Agent-friendly AnimaGuru CLI built with CrustJS",
   type: "module",
   bin: {
@@ -45269,6 +45269,7 @@ import { chmod as chmod2, mkdir as mkdir4, readFile as readFile2, rename as rena
 import { dirname as dirname3, join as join4, resolve as resolve3 } from "node:path";
 import { homedir as homedir3 } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+var USER_AGENT = `animaguru-cli/${package_default.version}`;
 function serverUrl(value) {
   const url3 = new URL(value);
   if (url3.username || url3.password || url3.search || url3.hash || url3.pathname !== "/") throw new Error("Use an origin URL without credentials, path, query or fragment.");
@@ -45338,14 +45339,15 @@ var Client = class {
     const idempotency = generation ? { "Idempotency-Key": generationRequestId(path, options.body) } : {};
     const response = await fetch(`${this.origin}${path}`, {
       method: options.method ?? "GET",
-      headers: { Origin: this.origin, ...token3 ? { Authorization: `Bearer ${token3}` } : {}, ...options.body instanceof Blob ? { "Content-Type": options.body.type || "application/octet-stream" } : options.body !== void 0 && !(options.body instanceof FormData) ? { "Content-Type": "application/json" } : {}, ...idempotency, ...options.headers },
+      headers: { Origin: this.origin, "User-Agent": USER_AGENT, ...token3 ? { Authorization: `Bearer ${token3}` } : {}, ...options.body instanceof Blob ? { "Content-Type": options.body.type || "application/octet-stream" } : options.body !== void 0 && !(options.body instanceof FormData) ? { "Content-Type": "application/json" } : {}, ...idempotency, ...options.headers },
       body: options.body instanceof FormData || options.body instanceof Blob ? options.body : options.body === void 0 ? void 0 : JSON.stringify(options.body),
       redirect: "error",
       signal: this.signal ? AbortSignal.any([this.signal, AbortSignal.timeout(options.timeout ?? 3e4)]) : AbortSignal.timeout(options.timeout ?? 3e4)
     });
     if (response.ok && options.raw) return response;
     const data = await response.json();
-    if (!response.ok) throw new ServiceError(response.status, typeof data.error === "string" ? data.error : "request_failed", data.error_description ?? (typeof data.error === "object" ? data.error.message : void 0) ?? data.message ?? `Request failed (${response.status}).`);
+    const code = typeof data.error === "string" ? data.error : typeof data.error?.code === "string" ? data.error.code : "request_failed";
+    if (!response.ok) throw new ServiceError(response.status, code, data.error_description ?? (typeof data.error === "object" ? data.error.message : void 0) ?? data.message ?? `Request failed (${response.status}).`);
     return data;
   }
 };
@@ -51063,6 +51065,7 @@ async function curl(options, io) {
     if (!headers.has("content-type")) headers.set("Content-Type", parsesAsJson(body) ? "application/json" : "application/x-www-form-urlencoded");
   }
   headers.set("Authorization", `Bearer ${await sessionToken(url3.origin)}`);
+  if (!headers.has("user-agent")) headers.set("User-Agent", USER_AGENT);
   if (!headers.has("origin")) headers.set("Origin", url3.origin);
   const method = (options.request ?? (options.uploadFile !== void 0 ? "PUT" : body !== void 0 ? "POST" : "GET")).toUpperCase();
   const timeout = AbortSignal.timeout(options.maxTime * 1e3);
@@ -51350,8 +51353,8 @@ Confirm code: ${device.user_code}`);
         else if (e.code !== "authorization_pending") throw e;
       }
     }
-    throw new Error("Device code expired. Run auth login again.");
-  }))).add(defineCommand("status", { description: "Show the signed-in user" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).action(async ({ flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request("/api/v1/me"))))).add(defineCommand("logout", { description: "Revoke the CLI session and remove its saved credentials" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).action(async ({ flags, stdout, signal }) => {
+    throw new Error(`Device code expired. Run auth login again. If the browser said the CLI needs a plan, choose one at ${client.origin}/app/billing first: every account starts with a 7-day Individual Starter trial, and members of a team on the Team plan are covered by it.`);
+  }))).add(defineCommand("status", { description: "Show the signed-in user, its plan or Starter trial, and whether the CLI can act for it (agents)" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).action(async ({ flags, stdout, signal }) => out(stdout, await new Client(flags.url, signal).request("/api/v1/me"))))).add(defineCommand("logout", { description: "Revoke the CLI session and remove its saved credentials" }, (command) => command.flags({ name: "url", type: "string", default: "https://animaguru.com", env: { name: "ANIMAGURU_URL" }, description: "Server origin" }).action(async ({ flags, stdout, signal }) => {
     const client = new Client(flags.url, signal);
     try {
       await client.request("/api/auth/sign-out", { method: "POST", body: {} });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/animaguru",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Agent-friendly AnimaGuru CLI built with CrustJS",
   "type": "module",
   "bin": {

package/skills/animaguru/SKILL.md

@@ -18,6 +18,7 @@ Before creative work in a multi-animation workspace, select or create the intend
 Share the [animation-style gallery](https://animaguru.com/animation-styles), or open that URL in the internal browser when available, while asking the user to choose a style. Read the installed `animaguru.templates.json` for available styles and their skill names; `animaguru templates` lists the current CLI catalog. Offer the local catalog's choices so users select a skill actually installed in their workspace. Templates define appearance and motion; derive audience, message and story from the brief. Local scaffolding is separate from `projects create`, which creates a remote asset project. Never run `create` over an existing workspace.
 
 - Run `animaguru schema` for the installed command structure and flags, and `animaguru catalog` for styles, subject kinds, actions, asset types, models, video settings, and speech voices; `catalog --type music|speech|sfx|model|image|vector|gif|video|sprites|avatars` prints one section. Use `--help` on a leaf command for details.
+- AnimaGuru's CLI needs a plan on the account: Individual Starter, Individual Pro or Team. Every account starts with a 7-day Individual Starter trial, and members of a team on the Team plan are covered. `animaguru auth status` shows `plan` (with `trial.endsAt` during the trial) and `agents.allowed`. A `plan_required` error (HTTP 403), or a browser sign-in that says the CLI needs a plan, means the account has none: tell the person to choose a plan at https://animaguru.com/app/billing, and don't retry or work around it. The browser studio keeps working with their credits.
 - Check `animaguru auth status`, `animaguru workspaces list`, and `animaguru credits` before generation. If sign-in is needed, run `animaguru auth login --no-browser` and let the user approve the printed browser URL. Select the user's requested Personal or team workspace with `animaguru workspaces use personal|TEAM_ID` before listing or creating projects. Do not read or print stored credentials. Agent runners may inject `ANIMAGURU_TOKEN` and `ANIMAGURU_WORKSPACE` as secrets or configuration.
 - The default service is `https://animaguru.com`. Respect an existing `ANIMAGURU_URL` or pass `--url` to the leaf command when the user chooses another service. HTTP is supported only for loopback development.
 - `animaguru skills install [--dir PATH]` (CLI 0.28.0) installs every AnimaGuru and PixiJS skill, the latest published on animaguru.com, into `.claude/skills/` and `.agents/skills/` with `npx skills`, and records them in `skills-lock.json`; run it when the user wants the skills in a folder or refreshed. `npx skills update --project --yes` refreshes them later. In a workspace made by an older CLI, newer skills may name commands or kit helpers its code lacks, so suggest updating the workspace as well.
@@ -153,7 +154,7 @@ CLI 0.20.0 also adds quiz films for educational explainers, lessons and training
 
 ## Asset library
 
-Pro and Team accounts: `animaguru library search DESCRIPTION [--type sprite|image|video|music|speech|sfx] [--labels a,b]` finds ready-made assets; `animaguru library import ID --project PROJECT_ID` copies one into a project and `animaguru library download ID --output DIR` saves its files. Search it before generating common assets (whooshes, background music, stock clips, characters); importing spends no credits.
+Every plan (Individual Starter and its trial, Individual Pro, Team): `animaguru library search DESCRIPTION [--type sprite|image|video|music|speech|sfx] [--labels a,b]` finds ready-made assets; `animaguru library import ID --project PROJECT_ID` copies one into a project and `animaguru library download ID --output DIR` saves its files. Search it before generating common assets (whooshes, background music, stock clips, characters); importing spends no credits.
 
 ## Saved brand kits
 

package/skills/animaguru/references/cloud.md

@@ -4,7 +4,7 @@ Read from the `animaguru` skill only when the user asks for cloud sync, versions
 
 ## Cloud sync and versions
 
-CLI 0.11.0 adds `animaguru cloud` for users on Individual Pro or Team. Discover it in `animaguru schema`. Commands run from anywhere inside a video workspace; `--dir PATH` selects another folder.
+CLI 0.11.0 adds `animaguru cloud` for users on Individual Starter (including its 7-day trial), Individual Pro or Team. Discover it in `animaguru schema`. Commands run from anywhere inside a video workspace; `--dir PATH` selects another folder.
 
 Only link a folder when the user asks for cloud sync. A folder syncs with one AnimaGuru project's animations, shown on that project's Animations tab in the studio. `cloud link --project PROJECT_ID` syncs with an existing project (`prj_…`); without it, `cloud link` creates a new project named after the folder (or `--name`) in the selected AnimaGuru workspace (`workspaces use` picks a team). In a linked folder:
 
@@ -16,4 +16,4 @@ Only link a folder when the user asks for cloud sync. A folder syncs with one An
 
 `cloud versions` lists history. `cloud restore VERSION [--path P]` brings back an earlier version without rewriting history; then push to save it as the newest version. Restore refuses to replace unsaved changes unless `--yes`, and needs the user's go-ahead. `cloud clone PROJECT_ID DIR` downloads a project; run `npm install` there. `cloud list` lists projects with synced animations. `cloud delete PROJECT_ID --yes` permanently removes the project's animations: every version, Animator draft and stored file, while the project and its assets stay. Run it only when the user asks to delete those animations.
 
-Sync never uploads node_modules, exports, frames, `.env` files, credentials, keys, links or `.gitignore`/`.animaguruignore` matches. Add bulky regenerable files to `.animaguruignore` rather than deleting them. Images, video, audio and ZIP files are stored once in cloud storage at any size and count toward the plan's media storage (20 GB Pro, 100 GB per Team). Every other file is versioned in Git. A work file over 32 MB stops the push: tell the user, and ignore or move it only with their agreement. If the plan ended, pushing is refused, but pulling and cloning still work. Never read or print `.animaguru/sync/` tokens; the CLI requests short-lived Git credentials itself.
+Sync never uploads node_modules, exports, frames, `.env` files, credentials, keys, links or `.gitignore`/`.animaguruignore` matches. Add bulky regenerable files to `.animaguruignore` rather than deleting them. Images, video, audio and ZIP files are stored once in cloud storage at any size and count toward the plan's media storage (5 GB Starter, 20 GB Pro, 100 GB per Team). Every other file is versioned in Git. A work file over 32 MB stops the push: tell the user, and ignore or move it only with their agreement. If the workspace's plan ended, pushing is refused, but pulling and cloning still work while the account itself has a plan; on `plan_required`, tell the person to choose a plan at https://animaguru.com/app/billing, and that the studio's Animations tab still downloads the films. Never read or print `.animaguru/sync/` tokens; the CLI requests short-lived Git credentials itself.