Python
Support user-wide skill installation and simplify install commands
Rohit Pa213efe22e96
diff --git a/docs/harness/guides/desktop.md b/docs/harness/guides/desktop.mdindex 8b404b8f..16ff393a 100644--- a/docs/harness/guides/desktop.md+++ b/docs/harness/guides/desktop.md@@ -42,31 +42,32 @@ you build. Run the relevant tests and prepare a local package.<details><summary>Install the skill for this project</summary>-After npm publication, install the matching skill in your existing app project.-The candidate below is not published yet; for local archives or checkout installation,-see the [skill installation guide](../../../skills/README.md).+Run one of these commands from your app project to install the latest published+skill. No OpenWorker repository checkout is required.<!-- sdk-install-tabs -->### Codex```sh frame="none"-npx @openworkerai/[email protected] --agent codex --project .+npx @openworkerai/build-with-sdk-skills --agent codex --project .```### Claude Code```sh frame="none"-npx @openworkerai/[email protected] --agent claude --project .+npx @openworkerai/build-with-sdk-skills --agent claude --project .```<!-- /sdk-install-tabs -->Open a new coding-agent session in that project. The installer copies the sameskill, SDK snippets and Desktop/Web references into the tool's project skills directory.-It doesn't change global settings or overwrite an existing skill. See the-[skill installation guide](../../../skills/README.md) for local candidate installation-and invocation details.+For all your projects on this machine, replace `--project .` with `--global`.+That installs to your user skills directory; neither mode overwrites an existing+skill. The `--global` option is new in the pending skills `0.1.0-beta.2` release.+See the [skill installation guide](../../../skills/README.md) for availability,+local candidate installation and invocation details.</details>diff --git a/docs/harness/guides/server.md b/docs/harness/guides/server.mdindex 933662c7..b4910ee7 100644--- a/docs/harness/guides/server.md+++ b/docs/harness/guides/server.md@@ -42,31 +42,32 @@ agent and session code, and prepare container deployment files.<details><summary>Install the skill for this project</summary>-After npm publication, install the matching skill in your existing app project.-The candidate below is not published yet; for local archives or checkout installation,-see the [skill installation guide](../../../skills/README.md).+Run one of these commands from your app project to install the latest published+skill. No OpenWorker repository checkout is required.<!-- sdk-install-tabs -->### Codex```sh frame="none"-npx @openworkerai/[email protected] --agent codex --project .+npx @openworkerai/build-with-sdk-skills --agent codex --project .```### Claude Code```sh frame="none"-npx @openworkerai/[email protected] --agent claude --project .+npx @openworkerai/build-with-sdk-skills --agent claude --project .```<!-- /sdk-install-tabs -->Open a new coding-agent session in that project. The installer copies the sameskill, SDK snippets and Desktop/Web references into the tool's project skills directory.-It doesn't change global settings or overwrite an existing skill. See the-[skill installation guide](../../../skills/README.md) for local candidate installation-and invocation details.+For all your projects on this machine, replace `--project .` with `--global`.+That installs to your user skills directory; neither mode overwrites an existing+skill. The `--global` option is new in the pending skills `0.1.0-beta.2` release.+See the [skill installation guide](../../../skills/README.md) for availability,+local candidate installation and invocation details.</details>diff --git a/harness/release/README.md b/harness/release/README.mdindex 093cfa0d..e47b1e34 100644--- a/harness/release/README.md+++ b/harness/release/README.md@@ -24,7 +24,7 @@ Native compilation and clean-machine testing are required on every claimed targeThe npm client is `@openworkerai/harness-sdk`; matching runtime packages are`@openworkerai/harness-runtime-<platform>-<arch>`. The same candidate includes`@openworkerai/build-with-sdk-skills`, which installs the shared Desktop/Web-skill into a Codex or Claude Code project. The skill package has no runtime or+skill into a Codex or Claude Code project, or user-wide with `--global`. The skill package has no runtime orSDK dependency. Its package version can advance independently;`openworkerSdkVersion` declares the compatible SDK release. To prepare just that archive without compiling Rust:diff --git a/skills/README.md b/skills/README.mdindex 7cd0d273..daa6465b 100644--- a/skills/README.md+++ b/skills/README.md@@ -6,24 +6,24 @@ snippets and separate Desktop/Web references. No OpenWorker checkout is requiredfor the packaged skill, and installing it does not install the SDK or a runtime.**Release candidate:** `@openworkerai/[email protected]` is prepared-locally. Registry commands below apply after publication; the version in this-repository does not mean it has been published.+locally. The new `--global` option and Railway guidance require this release;+until it is published, use the local candidate instructions below to try them.-## Install in your app project+## Install the skill-After publication, from an existing app project:+From an existing app project, install the latest published skill:```sh-npx @openworkerai/[email protected] --agent codex --project .+npx @openworkerai/build-with-sdk-skills --agent codex --project .```For Claude Code:```sh-npx @openworkerai/[email protected] --agent claude --project .+npx @openworkerai/build-with-sdk-skills --agent claude --project .```-The installer creates `.agents/skills/openworker-apps/` for Codex or+These project commands create `.agents/skills/openworker-apps/` for Codex or`.claude/skills/openworker-apps/` for Claude Code. It supports quoted project pathson Windows and macOS, leaves global settings alone, and refuses to overwrite anexisting skill. Review/back up an existing installation before replacing it.@@ -31,7 +31,30 @@ existing skill. Review/back up an existing installation before replacing it.checkout paths or credentials. Use `sdkVersion` from that file for the SDK. Skill and SDK package versions maydiffer; this skill candidate targets SDK `0.1.0-beta.1`.-The skill is discoverable in that project. Restart the coding-agent session if it+### Across your projects++For user-wide installation, use `--global` instead of `--project`:++```sh+npx @openworkerai/build-with-sdk-skills --agent claude --global+```++```sh+npx @openworkerai/build-with-sdk-skills --agent codex --global+```++This installs into `~/.claude/skills/openworker-apps/` for Claude Code or+`~/.agents/skills/openworker-apps/` for Codex, making the skill available across+projects for your user on this machine. It does not install into Claude web or+Cowork, change account settings, or require `npm install -g` or administrator+access. Choose either `--global` or `--project`, not both. Both modes preserve an+existing installation.++Unversioned commands select npm's `latest` release. To pin an installation for+reproducibility, append `@<version>` to the package name. The installer records+the compatible SDK version separately; the skill and SDK versions may differ.++The skill is discoverable in the selected scope. Restart the coding-agent session if itdoes not appear. Invoke `$openworker-apps` in Codex or `/openworker-apps` in ClaudeCode, or ask:@@ -46,8 +69,17 @@ and Docker assets. The default is one Node service serving the frontend and API,with the Rust harness running as a managed child process. The recipe has been tested locally and on Railway with thepublished SDK, including streamed Claude responses and conversation recoveryafter redeployment. Vercel recipes and a cluster-operations skill will-follow separately. This installer-targets local Codex and Claude Code projects, not Claude web/Cowork uploads.+follow separately. This installer targets local Codex and Claude Code sessions.++## Claude workspace uploads++Claude's **Customize → Skills → Upload** is a separate installation route.+For that flow, zip the complete installed `openworker-apps` directory, including+its references, Docker assets and `references/installation.json`; uploading only+`SKILL.md` loses the supporting files. The npm `.tgz` package is not this upload+format. Uploading a skill provides instructions, not an installed SDK, runtime,+or permission to deploy an app. The workspace upload flow has not been qualified+by this package's local installer tests.## Try the local candidatediff --git a/skills/install.mjs b/skills/install.mjsindex 2cd651e9..fc22a390 100644--- a/skills/install.mjs+++ b/skills/install.mjs@@ -1,17 +1,31 @@#!/usr/bin/env node-// Project-local installation only; never overwrite an existing skill.+// Project or user-wide installation; never overwrite an existing skill.import { mkdir, lstat, realpath, readFile, writeFile } from 'node:fs/promises';import { dirname, join, resolve } from 'node:path';import { fileURLToPath } from 'node:url';+import { homedir } from 'node:os';+import { parseArgs } from 'node:util';const source = dirname(fileURLToPath(import.meta.url));+const usage = 'build-with-sdk-skills --agent codex|claude (--project /path/to/your-app | --global)';const files = ['SKILL.md','references/desktop.md','references/web.md','references/sdk.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore','agents/openai.yaml'];-export async function install({agent, project}) {- if (!['codex','claude'].includes(agent) || !project) throw Error('Use --agent codex|claude --project /path/to/your-app');+function validate({agent, project, global: userWide = false}) {+ if (!['codex','claude'].includes(agent) || typeof userWide !== 'boolean' ||+ (project !== undefined && (typeof project !== 'string' || !project.trim())) ||+ userWide === (project !== undefined)) throw Error(`Use ${usage}; choose exactly one installation scope.`);+}+export function parseInstallArgs(args) {+ const {values} = parseArgs({args, options:{agent:{type:'string'}, project:{type:'string'}, global:{type:'boolean'}}});+ validate(values);+ return values;+}+export async function install(options, {userHome = homedir()} = {}) {+ validate(options);+ const {agent, project, global: userWide = false} = options;const pkg = JSON.parse(await readFile(join(source,'package.json'),'utf8'));// Validate package completeness before creating an installation directory.const content = await Promise.all(files.map(name => readFile(join(source,'openworker-apps',name))));- const root = await realpath(project);- if (!(await lstat(root)).isDirectory()) throw Error('Project must be an existing directory.');+ const root = await realpath(userWide ? userHome : project);+ if (!(await lstat(root)).isDirectory()) throw Error('Installation root must be an existing directory.');let parent = root;for (const component of [agent === 'codex' ? '.agents' : '.claude', 'skills']) {parent = join(parent, component);@@ -32,11 +46,11 @@ export async function install({agent, project}) {}if (process.argv[1] && await realpath(process.argv[1]).catch(() => resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {const args=process.argv.slice(2);- if(args.length===1 && args[0]==='--help') console.log('build-with-sdk-skills --agent codex|claude --project /path/to/your-app');+ if(args.length===1 && args[0]==='--help') console.log(`${usage}\n--global installs for your user across projects on this machine (Codex: ~/.agents/skills; Claude Code: ~/.claude/skills).`);else {try {- if(args.length!==4 || args[0]!=='--agent' || args[2]!=='--project') throw Error('Use --agent codex|claude --project /path/to/your-app');- console.log(`Installed: ${await install({agent:args[1],project:args[3]})}\nOpen a new coding-agent session in that project to use openworker-apps.`);+ const options = parseInstallArgs(args);+ console.log(`Installed: ${await install(options)}\nOpen a new coding-agent session${options.global ? '' : ' in that project'} to use openworker-apps.`);} catch(error) { console.error(error.code==='EEXIST' ? 'An installation already exists. Review or back it up before replacing it.' : error.message);process.exitCode=1; }}}diff --git a/skills/install.test.mjs b/skills/install.test.mjsindex 36c58509..7ce6f040 100644--- a/skills/install.test.mjs+++ b/skills/install.test.mjs@@ -1,9 +1,9 @@import test from 'node:test';import assert from 'node:assert/strict';-import {mkdtemp,readFile,writeFile,rm,mkdir,symlink,readdir} from 'node:fs/promises';+import {mkdtemp,readFile,writeFile,rm,mkdir,symlink,readdir,realpath} from 'node:fs/promises';import {tmpdir} from 'node:os';import {join} from 'node:path';-import {install} from './install.mjs';+import {install,parseInstallArgs} from './install.mjs';for (const agent of ['codex','claude']) test(`install complete ${agent} skill; preserve existing content`, async()=>{const root=await mkdtemp(join(tmpdir(),'ow skill '));try {@@ -22,6 +22,42 @@ for (const agent of ['codex','claude']) test(`install complete ${agent} skill; passert.equal(await readFile(join(dest,'SKILL.md'),'utf8'),'local customization');} finally {await rm(root,{recursive:true,force:true});}});+for (const agent of ['codex','claude']) test(`install ${agent} user-wide independently of project installs`,async()=>{+ const root=await mkdtemp(join(tmpdir(),'ow-global-skill-'));+ try {+ const userHome=join(root,'personal home'),project=join(root,'project');+ await mkdir(userHome);await mkdir(project);+ const local=await install({agent,project});+ const destination=await install({agent,global:true},{userHome});+ assert.equal(destination,join(await realpath(userHome),agent==='codex'?'.agents':'.claude','skills/openworker-apps'));+ for(const name of ['SKILL.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore'])+ assert.equal(await readFile(join(destination,name),'utf8'),await readFile(join(local,name),'utf8'));+ await writeFile(join(destination,'SKILL.md'),'personal customization');+ await assert.rejects(install({agent,global:true},{userHome}),{code:'EEXIST'});+ assert.equal(await readFile(join(destination,'SKILL.md'),'utf8'),'personal customization');+ assert.notEqual(await readFile(join(local,'SKILL.md'),'utf8'),'personal customization');+ } finally {await rm(root,{recursive:true,force:true});}+});+test('require exactly one scope and reject unknown CLI arguments',async()=>{+ const root=await mkdtemp(join(tmpdir(),'ow-skill-invalid-scope-'));+ try {+ assert.deepEqual({...parseInstallArgs(['--global','--agent','claude'])},{global:true,agent:'claude'});+ assert.deepEqual({...parseInstallArgs(['--project',root,'--agent','codex'])},{project:root,agent:'codex'});+ for(const args of [[],['--agent','claude'],['--global'],['--agent','claude','--global','--project',root],['--agent','claude','--global','extra'],['--agent','claude','--globall'],['--agent','claude','--project','']])+ assert.throws(()=>parseInstallArgs(args));+ await assert.rejects(install({agent:'claude',project:root,global:true},{userHome:root}),/exactly one/);+ await assert.rejects(install({agent:'claude',global:'yes'},{userHome:root}),/exactly one/);+ assert.deepEqual(await readdir(root),[]);+ } finally {await rm(root,{recursive:true,force:true});}+});+for(const folder of ['.agents','.claude'])test(`user-wide install refuses a linked ${folder} directory`,async()=>{+ const root=await mkdtemp(join(tmpdir(),'ow-global-linked-')),outside=await mkdtemp(join(tmpdir(),'ow-global-outside-'));+ try {+ await symlink(outside,join(root,folder),'junction');+ await assert.rejects(install({agent:folder==='.agents'?'codex':'claude',global:true},{userHome:root}),/real directory/);+ assert.deepEqual(await readdir(outside),[]);+ } finally {await rm(root,{recursive:true,force:true});await rm(outside,{recursive:true,force:true});}+});test('reject invalid agent and linked destination directories',async()=>{const root=await mkdtemp(join(tmpdir(),'ow-skill-scope-'));const outside=await mkdtemp(join(tmpdir(),'ow-skill-other-'));try {diff --git a/skills/package.test.mjs b/skills/package.test.mjsindex 2f2d5ff5..a0acb9c0 100644--- a/skills/package.test.mjs+++ b/skills/package.test.mjs@@ -4,6 +4,7 @@ import { mkdtemp, readFile, mkdir, readdir, rm, writeFile, realpath } from 'nodeimport { tmpdir } from 'node:os';import { join } from 'node:path';import { execFileSync } from 'node:child_process';+import { pathToFileURL } from 'node:url';import { prepare } from './prepare.mjs';test('packed installer works outside the checkout without SDK or native dependencies', {timeout: 60000}, async () => {@@ -32,6 +33,13 @@ test('packed installer works outside the checkout without SDK or native dependen? execFileSync(process.execPath,[join(installed,'install.mjs'),...args],{cwd:consumer,encoding:'utf8'}): execFileSync(bin,args,{cwd:consumer,encoding:'utf8'});assert.match(run(['--help']), /--agent codex\|claude/);+ assert.match(run(['--help']), /--global/);+ // Mock only the child's OS home resolver; never write to the developer's+ // actual home or override HOME/USERPROFILE while exercising the real CLI.+ const userHome=join(root,'personal home');await mkdir(userHome);+ const preload=join(root,'home-fixture.mjs');+ await writeFile(preload,`import os from 'node:os';import{syncBuiltinESMExports}from'node:module';os.homedir=()=>${JSON.stringify(userHome)};syncBuiltinESMExports();`);+ const runGlobal=(args)=>execFileSync(process.execPath,['--import',pathToFileURL(preload).href,join(installed,'install.mjs'),...args],{cwd:consumer,encoding:'utf8',stdio:'pipe'});for (const agent of ['codex','claude']) {const project = join(root, `new ${agent} app`);await mkdir(project);@@ -41,6 +49,15 @@ test('packed installer works outside the checkout without SDK or native dependenassert.equal(metadata.sdkVersion,pkg.openworkerSdkVersion);assert.equal(metadata.sdkPackage,'@openworkerai/harness-sdk');assert.equal(metadata.version,pkg.version);+ assert.match(runGlobal(['--agent',agent,'--global']),/Installed:/);+ const globalDest=join(userHome,agent==='codex'?'.agents':'.claude','skills/openworker-apps');+ assert.deepEqual(JSON.parse(await readFile(join(globalDest,'references/installation.json'),'utf8')),metadata);+ for(const file of ['SKILL.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore'])+ assert.equal(await readFile(join(globalDest,file),'utf8'),await readFile(join(dest,file),'utf8'));+ await assert.rejects(readFile(join(consumer,agent==='codex'?'.agents':'.claude','skills/openworker-apps/SKILL.md')),{code:'ENOENT'});+ await writeFile(join(globalDest,'SKILL.md'),'personal customization');+ assert.throws(()=>runGlobal(['--global','--agent',agent]));+ assert.equal(await readFile(join(globalDest,'SKILL.md'),'utf8'),'personal customization');for (const folder of ['', 'references', 'agents']) {for (const file of await readdir(join(dest,folder))) {if (!/\.(md|json|yaml)$/.test(file)) continue;