@ghship/cli 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# GHShip npm distribution
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Go CLI and home AI skill plus per-project integration. Package includes native
+binaries for macOS/Linux/Windows × amd64/arm64, with no postinstall downloads.
+
+After publication: `npx @ghship/cli@latest install` installs the home skill, same-version
+persistent CLI, then enters project initialization. `--user-only` stops after user
+installation. Project workflows need Git and a gh with native Issue relationships.
+`ghship doctor` provides official tool installation links when missing.
+
+Update/uninstall via external `npx @ghship/cli@latest update|uninstall`. Project lifecycle:
+`ghship project install|status|update|uninstall`; custom `.ghship/skill.md` is preserved.
+Users: `ghship user add|update|delete|list`; list validates tokens and reports actual
+expiry when GitHub returns it, otherwise unknown. Tokens never belong in projects.
+
+For a downloaded npm tarball, use:
+`npm exec --package /absolute/ghship.tgz -- ghship install --package-source /absolute/ghship.tgz`.
+Add `--user-only` to install shared tools without initializing a project.
+Registry commands require the selected version to be published.
+
+Detailed Chinese tutorial and AI skill: https://github.com/ghship/cli
+
+## License notices
+
+GHShip is distributed under the MIT License.
+
+MIT License
+
+Copyright (c) 2026 GHShip contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The bundled Go binary includes golang.org/x/sys and golang.org/x/term,
+which share the following BSD 3-Clause license:
+
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The bundled binaries include the Go runtime and standard library,
+distributed under the following BSD 3-Clause license:
+
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/checksums.json

@@ -0,0 +1,8 @@
+{
+  "bin/darwin-amd64/ghship": "f6c0f2c362d2a8631a4797976b775b918e14e4073414442abe7a6130adf125c5",
+  "bin/darwin-arm64/ghship": "6dd13e6d4b114308945119919728b50e2d97340f08d1405b9ddc58306d4fbfbb",
+  "bin/linux-amd64/ghship": "738329d127602e603562aada7daa270e5114f4e1715d14d5f7281f2ab79d03ea",
+  "bin/linux-arm64/ghship": "082b7c6945e6cfd9242a894d7ffb93771cd74fceddd6699a895889e747d5fff6",
+  "bin/windows-amd64/ghship.exe": "81c84b93a067b756de38bb2670d9b128801bdbf5ec081f296ea74de147f16621",
+  "bin/windows-arm64/ghship.exe": "7ddcae142e6d00e8706b5b29e447c6f83d0cb2bd650d99811ba01456f1776bc7"
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@ghship/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Go CLI and AI skill for native GitHub delivery pipelines",
+  "bin": {
+    "ghship": "run.cjs"
+  },
+  "files": [
+    "run.cjs",
+    "bin",
+    "README.md",
+    "checksums.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ghship/cli.git"
+  },
+  "scripts": {
+    "test": "node --test test.cjs"
+  },
+  "license": "MIT"
+}

package/run.cjs

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { spawn, spawnSync } = require('node:child_process');
+function binaryPath(platform = process.platform, arch = process.arch) {
+ const os = {darwin:'darwin', linux:'linux', win32:'windows'}[platform];
+ const cpu = {x64:'amd64', arm64:'arm64'}[arch];
+ if (!os || !cpu) throw new Error(`Unsupported platform: ${platform}/${arch}`);
+ return path.join(__dirname, 'bin', `${os}-${cpu}`, os === 'windows' ? 'ghship.exe' : 'ghship');
+}
+function npmCommand() {
+ if (process.env.npm_execpath && fs.existsSync(process.env.npm_execpath)) return [process.execPath, [process.env.npm_execpath]];
+ const suffixes = process.platform === 'win32' ? ['npm.cmd'] : ['npm'];
+ for (const dir of (process.env.PATH || '').split(path.delimiter)) for (const name of suffixes) {
+  const candidate = path.join(dir, name); if (!fs.existsSync(candidate)) continue;
+  const real = fs.realpathSync(candidate);
+  if (process.platform !== 'win32') return [process.execPath, [real]];
+  const cli = path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  if (fs.existsSync(cli)) return [process.execPath, [cli]];
+ }
+ throw new Error('npm is unavailable. Install Node/npm: https://nodejs.org/en/download');
+}
+function npm(args, capture = false) {
+ const [command, base] = npmCommand();
+ const result = spawnSync(command, [...base, ...args], {stdio:capture ? ['ignore','pipe','pipe'] : 'inherit', encoding:'utf8'});
+ const absentList = args[0] === 'list' && result.status !== 0 && (() => {
+  try { const value=JSON.parse(result.stdout); return value.error?.code === 'ENOENT' || (result.status === 1 && !value.error); } catch (_) { return false; }
+ })();
+ if (result.error || (result.status !== 0 && !absentList)) throw new Error(`npm ${args[0]} failed; retry the same fixed-version command`);
+ return capture ? (absentList ? '{"dependencies":{}}' : result.stdout) : '';
+}
+function go(executable,args,capture=false,interactive=false) {
+ const result=spawnSync(executable,args,{stdio:capture?[interactive?'inherit':'ignore','pipe',interactive?'inherit':'pipe']:'inherit',encoding:'utf8'});
+ if(result.error) throw new Error('Cannot start the packaged Go CLI');
+ if (capture && result.status !== 0 && result.stderr) process.stderr.write(result.stderr);
+ return {code:result.status===null?1:result.status,stdout:result.stdout};
+}
+function hashFile(file) { return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'); }
+function noLinks(file) {
+ for(let current=file;;current=path.dirname(current)) {
+  try {if(fs.lstatSync(current).isSymbolicLink())throw new Error('Installation path contains a symlink; preserved');}
+  catch(error){if(error.code!=='ENOENT')throw error;}
+  if(path.dirname(current)===current)break;
+ }
+}
+function packageReceipt(root) {
+ const base=process.platform==='win32' ? path.join(process.env.APPDATA||path.join(os.homedir(),'AppData','Roaming'),'ghship') : path.join(os.homedir(),'.config','ghship');
+ return path.join(base,`npm-${crypto.createHash('sha256').update(root).digest('hex')}.json`);
+}
+function observePackage(root,meta,existing,replacingVerifiedReceipt=false) {
+ const directory=path.join(root,meta.name); noLinks(directory);
+ const metadata=JSON.parse(fs.readFileSync(path.join(directory,'package.json'),'utf8'));
+ if(metadata.name!==meta.name||metadata.version!==existing.version||metadata.bin?.ghship!=='run.cjs')throw new Error('Unrecognized global package; preserved');
+ const relative=path.relative(__dirname,binaryPath());
+ const observed={root,name:meta.name,version:metadata.version,launcher:hashFile(path.join(directory,'run.cjs')),binary:hashFile(path.join(directory,relative))};
+ const current=observed.version===meta.version&&observed.launcher===hashFile(path.join(__dirname,'run.cjs'))&&observed.binary===hashFile(binaryPath());
+ const receipt=packageReceipt(root);noLinks(receipt);
+ let recorded=null;try{recorded=JSON.parse(fs.readFileSync(receipt,'utf8'));}catch(error){if(error.code!=='ENOENT')throw new Error('Invalid installation receipt; preserved');}
+ if(recorded&&!replacingVerifiedReceipt&&!Object.keys(observed).every(key=>recorded[key]===observed[key]))throw new Error('Installation receipt does not match the package; preserved');
+ const managed=current||(recorded&&Object.keys(observed).every(key=>recorded[key]===observed[key]));
+ if(!managed)throw new Error('Global package ownership/content is unverified; preserved. Inspect npm list -g @ghship/cli before changing it');
+ return {observed,current};
+}
+function saveReceipt(root,observed) {
+ const file=packageReceipt(root);noLinks(file);fs.mkdirSync(path.dirname(file),{recursive:true,mode:0o700});
+ const stage=`${file}.${process.pid}.tmp`;const descriptor=fs.openSync(stage,'wx',0o600);
+ try{fs.writeFileSync(descriptor,JSON.stringify(observed));fs.fsyncSync(descriptor);}finally{fs.closeSync(descriptor);}
+ try{fs.renameSync(stage,file);}finally{if(fs.existsSync(stage))fs.unlinkSync(stage);}
+}
+function lifecycle(executable,args) {
+ const action=args[0], meta=require('./package.json'); let source=`${meta.name}@${meta.version}`;
+ const passed=args.slice(1); const sourceIndex=passed.indexOf('--package-source');
+ if(sourceIndex>=0) {if(!passed[sourceIndex+1])throw new Error('--package-source requires a local tarball');source=path.resolve(passed[sourceIndex+1]);passed.splice(sourceIndex,2);
+  const packed=JSON.parse(npm(['pack',source,'--dry-run','--json'],true));if(packed.length!==1||packed[0].name!==meta.name||packed[0].version!==meta.version)throw new Error('Local package source must match this exact package and version');
+ }
+ const lifecycleArgs=[];const initArgs=[];let userOnly=false;
+ const initValues=new Set(['--project','--repo','--author','--reviewer','--admin','--acceptance-pr']);
+ const initSwitches=new Set(['--configure','--non-interactive','--confirm-auto-close']);
+ for(let i=0;i<passed.length;i++){
+  const arg=passed[i];
+  if(arg==='--user-only'){userOnly=true;continue;}
+  if(arg==='--dir'){if(!passed[i+1])throw new Error('--dir requires a path');lifecycleArgs.push(arg,passed[++i]);}
+  else if(arg==='--json'||initSwitches.has(arg)){initArgs.push(arg);}
+  else if(initValues.has(arg)){if(!passed[i+1])throw new Error(`${arg} requires a value`);initArgs.push(arg,passed[++i]);}
+  else throw new Error(`Unknown lifecycle option: ${arg}; use ghship help install`);
+ }
+ const preflight=go(executable,[action,'--skill-only','--check',...lifecycleArgs,'--json'],true);if(preflight.code!==0)return preflight.code;
+ const installed=JSON.parse(npm(['list','-g',meta.name,'--depth=0','--json'],true));
+ const existing=installed.dependencies && installed.dependencies[meta.name];
+ const root=path.resolve(npm(['root','-g'],true).trim());
+ const receipt=packageReceipt(root);noLinks(receipt);
+ if(!existing&&action!=='uninstall'&&fs.existsSync(receipt))throw new Error('Installation receipt exists without its package; preserved');
+ if(existing && (existing.invalid||existing.extraneous))throw new Error('Global package ownership is inconsistent; inspect npm list -g @ghship/cli');
+ const observation=existing ? observePackage(root,meta,existing) : null;
+ if(action==='uninstall') {
+  const removal=go(executable,['uninstall','--skill-only',...lifecycleArgs,'--json'],true);if(removal.code!==0)return removal.code;
+  if(existing)npm(['uninstall','-g',meta.name],true);
+  const receipt=packageReceipt(root);noLinks(receipt);if(existing&&fs.existsSync(receipt))fs.unlinkSync(receipt);
+  console.log(JSON.stringify({userInstalled:false,projectConfigurationsPreserved:true,credentialsPreserved:true}));return 0;
+ }
+ const skill=go(executable,['install','--skill-only',...lifecycleArgs,'--json'],true);if(skill.code!==0)return skill.code;
+ try{if(!observation||!observation.current)npm(['install','-g',source],true);}catch(error){console.error(`Skill is ${meta.version}; CLI installation incomplete. Retry npx ${meta.name}@${meta.version} ${action}`);throw error;}
+ const verified=JSON.parse(npm(['list','-g',meta.name,'--depth=0','--json'],true));
+ if(!verified.dependencies||verified.dependencies[meta.name]?.version!==meta.version)throw new Error('Installed CLI version does not match skill; installation incomplete');
+ const persisted=observePackage(root,meta,verified.dependencies[meta.name],!!observation);if(!persisted.current)throw new Error('Persistent CLI content does not match this package');
+ const runtimeVersion=go(path.join(root,meta.name,path.relative(__dirname,executable)),['version'],true);
+ if(runtimeVersion.code!==0||runtimeVersion.stdout.trim()!==meta.version)throw new Error('Persistent CLI cannot run the expected version');
+ saveReceipt(root,persisted.observed);
+ if(action==='update'||userOnly){console.log(JSON.stringify({userInstalled:true,version:meta.version,projectInitialized:false}));return 0;}
+ const init=go(executable,['init',...initArgs,'--json'],true,true);
+ let result;try{result=JSON.parse(init.stdout);}catch(_){result={ready:false,missing:['Initialization failed before producing a result'],next:['ghship init --json']};}
+ result.userInstalled=true;result.version=meta.version;console.log(JSON.stringify(result));return init.code;
+}
+module.exports = {binaryPath};
+if(require.main===module) {
+ try {
+  const executable=binaryPath();if(!fs.existsSync(executable))throw new Error('Package missing Go binary; reinstall the package');
+  const args=process.argv.slice(2);const action=args[0];
+  if(['install','update','uninstall'].includes(action)&&!args.includes('--standalone')&&!args.includes('--skill-only')&&!args.includes('--help')){
+   if(action!=='install'&&process.env.npm_command!=='exec') {console.error(`Run npx @ghship/cli@latest ${action} from an external npm entry`);process.exitCode=4;}
+   else process.exitCode=lifecycle(executable,args);
+  } else {
+   const child=spawn(executable,args,{stdio:'inherit'});child.on('error',()=>{console.error('Cannot start Go CLI');process.exitCode=1});child.on('exit',(code,signal)=>{if(signal)process.kill(process.pid,signal);else process.exitCode=code===null?1:code});
+  }
+ }catch(error){console.error(error.message);process.exitCode=1;}
+}