@zalosai/zalos-cli 0.2.13 → 0.2.15

package/PUBLISHING.md

@@ -8,8 +8,9 @@ Zalos product access.
 
 - The release commit must be merged into `develop`.
 - The package version must not already exist in npm.
-- The repository `NPM_TOKEN` secret must have publish access to
-  `@zalosai/zalos-cli` on npm.
+- npm Trusted Publishing must authorize GitHub Actions from
+  `Zalos-io/mesh` through `publish-zalos-cli.yml`, with direct publishing
+  enabled.
 
 ## Release
 
@@ -38,8 +39,8 @@ Zalos product access.
    pnpm --filter @zalosai/zalos-cli exec npm pack --dry-run
    ```
 
-   Only `package.json`, `README.md`, `PUBLISHING.md`, and runtime JavaScript under `dist/`
-   should be included.
+   Only `package.json`, `README.md`, `PUBLISHING.md`, the bundled `skills/` Markdown, and runtime
+   JavaScript under `dist/` should be included.
 
 4. In GitHub, open **Actions → Publish Zalos CLI → Run workflow**.
    Select `develop` and enter the exact version from `package.json`. The workflow rejects
@@ -58,6 +59,10 @@ Do not publish with uncommitted package changes or reuse an existing version.
 
 ## Central developer access release
 
+Version 0.2.15 bundles the `zl-ops` production-operations skill and adds offline `zl skills`
+commands to list, read, and install it into Codex or Claude skill roots.
+Version 0.2.14 moves publishing to npm Trusted Publishing through the
+`publish-zalos-cli.yml` GitHub Actions workflow, so releases no longer rely on a stored npm token.
 Version 0.2.13 adds revision-safe Markdown import and export for team Pages. It converts common
 Tiptap process-document structures while rejecting unsupported stored nodes during export, and uses
 the `pages:read` and `pages:write` scopes for least-privilege API access.

package/README.md

@@ -11,11 +11,31 @@ Requires Node.js 22 or newer. The product CLI is public on npm and does not
 require GitHub CLI or GitHub Packages access.
 
 ```bash
-npm install --global @zalosai/zalos-cli@0.2.13
+npm install --global @zalosai/zalos-cli@0.2.15
 ```
 
 Installing the CLI does not grant access.
 
+## Agent skills
+
+The package includes a production-operations skill for Codex and Claude. It describes
+region selection, browser login, team switching, preview-first changes, workflow
+publishing, Team Files, Pages, and Motion work without embedding credentials.
+
+```bash
+zl skills list
+zl skills read zl-ops
+zl skills install zl-ops --target codex
+# Or:
+zl skills install zl-ops --target claude
+```
+
+Codex installs to `$CODEX_HOME/skills` when `CODEX_HOME` is set, otherwise `~/.codex/skills`;
+Claude installs to `~/.claude/skills`. Use `--directory <path>` to install beneath a custom skills
+root. Installation leaves an identical existing skill unchanged and refuses to replace local edits unless `--force` is
+explicitly supplied. These commands work locally and do not need authentication or an
+environment selection.
+
 ## First run
 
 ```bash

package/dist/commands/skills.js

@@ -0,0 +1,90 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ValidationError } from '../utils/errors.js';
+import { printJson } from '../utils/output.js';
+import { action } from '../utils/product-api.js';
+const OPS_SKILL_NAME = 'zl-ops';
+const OPS_SKILL_PATH = fileURLToPath(new URL('../../skills/zl-ops/SKILL.md', import.meta.url));
+function isSkillTarget(value) {
+    return value === 'claude' || value === 'codex';
+}
+function skillPath(name) {
+    if (name !== OPS_SKILL_NAME)
+        throw new ValidationError('skill', `Unknown skill: ${name}. Available: ${OPS_SKILL_NAME}`);
+    return OPS_SKILL_PATH;
+}
+export function resolveDefaultSkillsDirectory(target, home = homedir()) {
+    if (target === 'codex') {
+        const codexHome = process.env.CODEX_HOME;
+        if (codexHome)
+            return join(codexHome, 'skills');
+        return join(home, '.codex/skills');
+    }
+    return join(home, '.claude/skills');
+}
+function resolveInstallDirectory(options) {
+    if (options.directory && options.target)
+        throw new ValidationError('skills', 'Specify either --target or --directory, not both');
+    if (options.directory)
+        return resolve(options.directory);
+    if (!options.target)
+        throw new ValidationError('target', 'Choose --target codex or --target claude, or provide --directory');
+    if (!isSkillTarget(options.target))
+        throw new ValidationError('target', 'Expected --target codex or --target claude');
+    return resolveDefaultSkillsDirectory(options.target);
+}
+export async function readSkill(name) {
+    return readFile(skillPath(name), 'utf8');
+}
+async function existingContents(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function installSkill(name, options) {
+    const contents = await readSkill(name);
+    const directory = resolveInstallDirectory(options);
+    const destination = join(directory, name, 'SKILL.md');
+    const existing = await existingContents(destination);
+    if (existing === contents)
+        return { skill: name, status: 'unchanged', path: destination };
+    if (existing !== null && !options.force)
+        throw new ValidationError('destination', `Skill already exists at ${destination}; use --force to replace local changes`);
+    await mkdir(dirname(destination), { recursive: true, mode: 0o755 });
+    await writeFile(destination, contents, { mode: 0o644 });
+    return {
+        skill: name,
+        status: existing === null ? 'installed' : 'updated',
+        path: destination,
+    };
+}
+export function registerSkillsCommand(program) {
+    const command = program.command('skills').description('Read and install bundled agent skills');
+    command
+        .command('list')
+        .description('List bundled skills (no network or authentication required)')
+        .action(() => printJson({
+        skills: [{ name: OPS_SKILL_NAME, description: 'Zalos production operations' }],
+    }));
+    command
+        .command('read <name>')
+        .description('Print a bundled SKILL.md (no network or authentication required)')
+        .action(async (name) => action(async () => {
+        process.stdout.write(await readSkill(name));
+    }));
+    command
+        .command('install <name>')
+        .description('Install a bundled skill for Codex or Claude')
+        .option('--target <target>', 'Install into the standard codex or claude skill directory')
+        .option('--directory <path>', 'Install beneath a custom skills directory')
+        .option('--force', 'Replace a locally modified installed skill')
+        .action(async (name, options) => action(async () => printJson(await installSkill(name, options))));
+}
+//# sourceMappingURL=skills.js.map

package/dist/main.js

@@ -20,6 +20,7 @@ import { registerTaskCommentCommand } from './commands/task-comment.js';
 import { registerTaskCommand } from './commands/task.js';
 import { registerTeamCommand } from './commands/team.js';
 import { registerPageCommand } from './commands/page.js';
+import { registerSkillsCommand } from './commands/skills.js';
 import { configureApiUrlOverride, currentEnvironment } from './environments.js';
 import { handleError } from './utils/errors.js';
 const program = new Command();
@@ -41,8 +42,10 @@ program
     configureApiUrlOverride(opts.apiUrl);
     if (actionCommand.name() === 'zl' ||
         actionCommand.name() === 'schema' ||
+        actionCommand.name() === 'skills' ||
         (actionCommand.name() === 'validate' && actionCommand.parent?.name() === 'workflow') ||
-        actionCommand.parent?.name() === 'schema')
+        actionCommand.parent?.name() === 'schema' ||
+        actionCommand.parent?.name() === 'skills')
         return;
     try {
         currentEnvironment();
@@ -65,6 +68,7 @@ registerCredentialCommand(program);
 registerFileCommand(program);
 registerTeamCommand(program);
 registerPageCommand(program);
+registerSkillsCommand(program);
 registerSchemaCommand(program);
 registerStateCommand(program);
 registerLabelCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalosai/zalos-cli",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "API-only product command-line interface for Zalos",
   "repository": {
     "type": "git",
@@ -15,11 +15,21 @@
   "files": [
     "dist/**/*.js",
     "README.md",
-    "PUBLISHING.md"
+    "PUBLISHING.md",
+    "skills/**/*.md"
   ],
   "engines": {
     "node": ">=22"
   },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean && rm -rf dist",
+    "dev": "tsx src/main.ts",
+    "prepack": "pnpm clean && pnpm build",
+    "smoke:package": "node scripts/smoke-package.mjs",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit --types node --incremental --tsBuildInfoFile dist/tsconfig.typecheck.tsbuildinfo"
+  },
   "dependencies": {
     "@tiptap/core": "3.27.1",
     "@tiptap/extension-heading": "3.27.1",
@@ -41,13 +51,5 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
-  },
-  "scripts": {
-    "build": "tsc --build",
-    "clean": "tsc --build --clean && rm -rf dist",
-    "dev": "tsx src/main.ts",
-    "smoke:package": "node scripts/smoke-package.mjs",
-    "test": "vitest run",
-    "typecheck": "tsgo --noEmit --types node --incremental --tsBuildInfoFile dist/tsconfig.typecheck.tsbuildinfo"
   }
-}
+}

package/skills/zl-ops/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: zl-ops
+description: Operate Zalos production workflows, executions, Team Files, Pages, and Motion work through the public Zalos CLI.
+---
+
+# Zalos CLI Operations
+
+Use this skill when an operator needs to inspect or safely change Zalos data through `zl`.
+The CLI works against one production region at a time. Ask whether the task is in
+`us-prod` or `eu-prod` when it is not already specified; never infer a region.
+
+## Set up and verify access
+
+```bash
+node --version
+npm install --global @zalosai/zalos-cli@latest
+zl --environment <us-prod|eu-prod> auth login
+zl --environment <us-prod|eu-prod> auth status
+zl --environment <us-prod|eu-prod> team list
+```
+
+A current Zalos browser session completes login automatically. Only ask the user to
+interact with the browser if the browser itself requires sign-in or consent. Do not
+print credentials, profile files, or API tokens.
+
+Run `zl --version` and the relevant `--help` command before saying that a command or
+option is unavailable. An absent documented command usually means the global CLI needs
+an update.
+
+## Select the correct team
+
+`team list` returns the active memberships available to the signed-in user in the
+chosen region. Use its opaque `publicId` value, such as `tm_4ERk9QxW`:
+
+```bash
+zl --environment <us-prod|eu-prod> team switch <team-ref>
+```
+
+Switch the selected team before a change. A switch only works for a team the user can
+access and preserves the session expiry. For permitted read-only file inspection, use
+an explicit `--team-id <team-ref>` where the command supports it. Never treat a `tm_`
+reference as a UUID.
+
+## Inspect before changing
+
+Start with a small read and use fields to keep output focused:
+
+```bash
+zl --environment <us-prod|eu-prod> workflow list --fields id,name,active
+zl --environment <us-prod|eu-prod> workflow view <workflow-id>
+zl --environment <us-prod|eu-prod> execution list --limit 20
+zl --environment <us-prod|eu-prod> execution summary <execution-id>
+zl --environment <us-prod|eu-prod> page list --fields id,title,updatedAt
+zl --environment <us-prod|eu-prod> file tree --team-id <team-ref>
+```
+
+Use the IDs from command output. For an execution artifact, inspect the execution first,
+then download the immutable artifact through the authenticated CLI:
+
+```bash
+zl --environment <us-prod|eu-prod> execution artifact download <artifact-id> --output /tmp/artifact
+```
+
+## Make controlled changes
+
+For a supported mutation, preview it first. Review the response, then repeat the same
+command with `--apply` only when the intended team, object, and paths are confirmed.
+
+```bash
+zl --environment <us-prod|eu-prod> workflow update <workflow-id> --input /tmp/workflow.json --dry-run
+zl --environment <us-prod|eu-prod> workflow update <workflow-id> --input /tmp/workflow.json --apply
+zl --environment <us-prod|eu-prod> workflow publish <workflow-id> --apply
+```
+
+A workflow update saves a draft. Publish the workflow after reviewing its draft and
+live-version response; executions continue using the published version until then.
+
+For Team Files seeding, preview first, then use exactly the checksum returned by that
+preview:
+
+```bash
+zl --environment <us-prod|eu-prod> file seed --source-team-id <source-team-ref> --source-path /Fixtures --target-path /Rehearsal
+zl --environment <us-prod|eu-prod> file seed --source-team-id <source-team-ref> --source-path /Fixtures --target-path /Rehearsal --apply --expected-checksum <sha256>
+```
+
+## Pages and Motion work
+
+Pages use Markdown files with a revision marker. Export before editing, then preview
+and apply the update using that file:
+
+```bash
+zl --environment <us-prod|eu-prod> page export <page-id> --output /tmp/process.md
+zl --environment <us-prod|eu-prod> page update <page-id> --input /tmp/process.md --dry-run
+zl --environment <us-prod|eu-prod> page update <page-id> --input /tmp/process.md --apply
+```
+
+For Motion work, inspect the project and valid state IDs first. Use `--dry-run` for task
+creation, updates, moves, and comments whenever the command offers it.
+
+```bash
+zl --environment <us-prod|eu-prod> project list --fields id,name
+zl --environment <us-prod|eu-prod> state list --project-id <project-id> --fields id,name,type
+zl --environment <us-prod|eu-prod> task create --project-id <project-id> --json '{"title":"Example"}' --dry-run
+```
+
+## Get current command help
+
+```bash
+zl --help
+zl <resource> --help
+zl schema <resource>
+```
+
+Successful product commands emit JSON on stdout. Errors emit structured JSON on stderr
+and exit nonzero. Keep operational output focused on the requested object and report
+what was inspected, previewed, applied, and published.