@hyperscale0/create 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -4,7 +4,8 @@ The Hyperscale project launcher: `npm create @hyperscale0` scaffolds a
 minimal project wired to your Product's hosted TypeScript SDK. It pins the
 SDK version the registry serves today, writes the project `.npmrc` for the
 authenticated registry, puts your key in a gitignored `.env`, and generates
-a `hello.mjs` that makes the product's first read call.
+a `hello.mjs` that calls the selected parameterless SDK read or points to the
+SDK's tailored first-call example.
 
 ## Use
 
@@ -21,4 +22,4 @@ bunx @hyperscale0/create my-product
 There are no prompts: every input is a flag or an environment variable.
 Point it at another host with `--base-url`, and at the live plane with
 `--environment live`. Run `bunx @hyperscale0/create --help` for the full
-option list.
+option list. Add `--json` for machine-readable success and failure output.

package/create-hyperscale.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import{spawn as b}from"node:child_process";import{existsSync as x,mkdirSync as P,readdirSync as T,writeFileSync as L}from"node:fs";import{basename as K,join as O,resolve as v}from"node:path";const E="https://hyperscale0.ai",S="sandbox",k="hyperscale-app",I=3e4,C=`bunx @hyperscale0/create [directory] [options]
+import{spawn as U}from"node:child_process";import{existsSync as K,mkdirSync as P,readdirSync as T,writeFileSync as L}from"node:fs";import{basename as O,join as D,resolve as S}from"node:path";const E="https://hyperscale0.ai",k="sandbox",A="hyperscale-app",I=3e4,C=`bunx @hyperscale0/create [directory] [options]
 
 Scaffolds a minimal project wired to your Product's hosted TypeScript SDK:
 a package.json pinned to the SDK version the registry serves today, a
 project .npmrc for the authenticated registry, a .env carrying the key from
-your environment, and hello.mjs making the product's first read call.
+your environment, and hello.mjs calling the selected parameterless SDK read or
+pointing to the SDK's tailored first-call example.
 
 Options:
   --api-key <key>            Product API key (default: $HYPERSCALE_API_KEY)
   --base-url <url>           API origin (default: $HYPERSCALE_BASE_URL, else ${E})
-  --environment <name>       sandbox or live (default: $HYPERSCALE_ENVIRONMENT, else ${S})
+  --environment <name>       sandbox or live (default: $HYPERSCALE_ENVIRONMENT, else ${k})
   --no-install               Write the project without running npm install
   --json                     Print a machine-readable summary
   --version                  Print the launcher version
@@ -26,8 +27,8 @@ Examples:
   npm create @hyperscale0
   bunx @hyperscale0/create my-product
   bunx @hyperscale0/create my-product --no-install
-`;class a extends Error{}const j=new Set(["--api-key","--base-url","--environment"]),D=new Set(["--help","--json","--no-install","--version"]);function H(e){const t=[],n={};for(let r=0;r<e.length;r+=1){const s=e[r];if(!s.startsWith("--")){t.push(s);continue}if(j.has(s)){const o=e[r+1];if(o===void 0)throw new a(`${s} needs a value`);n[s]=o,r+=1;continue}if(D.has(s)){n[s]=!0;continue}throw new a(`Unknown option: ${s}`)}return{flags:n,positional:t}}function Y(e,t){const n=e["--api-key"]??t.HYPERSCALE_API_KEY;if(!n)throw new a("No API key. Set HYPERSCALE_API_KEY, or pass --api-key. Request access at https://hyperscale0.ai/request-access.");const r=e["--environment"]??t.HYPERSCALE_ENVIRONMENT??S;if(r!=="sandbox"&&r!=="live")throw new a(`Unknown environment: ${r}. Use sandbox or live.`);const s=(e["--base-url"]??t.HYPERSCALE_BASE_URL??E).replace(/\/+$/,"");return{apiKey:n,baseUrl:s,environment:r}}async function A(e,t){try{const n=await fetch(t,{headers:{accept:"application/json",authorization:`Bearer ${e.apiKey}`,"x-hyperscale-environment":e.environment},signal:AbortSignal.timeout(I),redirect:"manual"});if(n.status>=300&&n.status<400)throw new a(`${t} redirected, so the key was not sent on. Point --base-url at the origin the API answers on; the usual cause is http:// where it serves https://.`);return{response:n,text:V(await n.text())}}catch(n){throw n instanceof a?n:new a(`Could not reach ${t}: ${n.message}`)}}async function F(e){const{response:t,text:n}=await A(e,`${e.baseUrl}/v1/llms.txt`);if(!t.ok)throw N(t,n);const r=/^# (.+)$/m.exec(n),s=/^## Operations \((\d+)\)$/m.exec(n),o=/^- Auth: \S+ \(secret via (\S+)\)$/m.exec(n);if(!r||!s||!o)throw new Error("The product document is not in the expected format; upgrade the launcher.");const i=o[1];if(!/^HYPERSCALE_[A-Z0-9_]*$/.test(i))throw new a(`The product document names an invalid auth environment variable (${i}); refusing to scaffold.`);const c=[],d=/^- ([A-Z]+) (\S+) · (\S+) \((\S+); idempotency (\S+)\)$/gm;for(const u of n.matchAll(d))c.push({method:u[1],operationId:u[4],path:u[2]});const h=Number(s[1]);if(c.length!==h)throw new Error(`The product document declares ${h} operations but ${c.length} parsed; upgrade the launcher.`);const l=new Map,_=/^ {2}\d+\. (\S+) \(([^)]+)\)$/gm;for(const u of n.matchAll(_)){const y=u[1];if(!/^[A-Za-z_$][\w$]*$/.test(y))throw new a(`The product document names an invalid SDK function (${y}); refusing to scaffold.`);const[$,U]=u[2].split("; ");U!=="gap"&&!l.has($)&&l.set($,y)}const g=/^- Package: (.+)$/m.exec(n),w=/^- Registry: (\S+)$/m.exec(n);if(!g||!w)throw new a("This Product has no hosted SDK yet. Build it in the composer, then rerun.");const m=g[1].trim();if(!/^@hyperscale\/[a-z0-9][a-z0-9._-]*$/.test(m))throw new a(`The product document names an invalid SDK package (${m}); refusing to scaffold.`);const f=w[1].replace(/\/+$/,"");if(B(f)!==new URL(e.baseUrl).origin)throw new a(`The product document names a registry on another origin (${f}); refusing to scaffold.`);return{apiKeyEnvVar:i,operations:c,packageName:m,registryUrl:f,sdkFunctionByOperationId:l,title:r[1].trim()}}function V(e){return e.replace(/\p{Cc}/gu,t=>`	
-\r`.includes(t)?t:"")}function B(e){try{return new URL(e).origin}catch{return null}}async function J(e,t){const n=encodeURIComponent(t.packageName).replace("%40","@"),{response:r,text:s}=await A(e,`${t.registryUrl}/${n}`);if(!r.ok)throw N(r,s);let o;try{o=JSON.parse(s)["dist-tags"]?.latest}catch{o=void 0}if(typeof o!="string")throw new a(`The registry packument for ${t.packageName} names no latest version; upgrade the launcher.`);if(!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(o))throw new a(`The registry packument for ${t.packageName} names ${o} as its latest version, which is not a version; refusing to scaffold.`);return o}function N(e,t){let n=t.trim();try{const r=JSON.parse(t);r&&r.error&&typeof r.error.message=="string"&&(n=`${r.error.code}: ${r.error.message}`)}catch{}return new a(`HTTP ${e.status}${n?` \xB7 ${n}`:""}`)}function R(e){const t=e.operations.find(n=>n.method==="GET"&&!n.path.includes("{")&&e.sdkFunctionByOperationId.has(n.operationId));if(t)return e.sdkFunctionByOperationId.get(t.operationId)}function M(e,t){const n=`// Generated by @hyperscale0/create for ${e.title}.
+`;class a extends Error{}const j=new Set(["--api-key","--base-url","--environment"]),H=new Set(["--help","--json","--no-install","--version"]);function F(e){const t=[],n={};for(let r=0;r<e.length;r+=1){const s=e[r];if(!s.startsWith("--")){t.push(s);continue}if(j.has(s)){const o=e[r+1];if(o===void 0)throw new a(`${s} needs a value`);n[s]=o,r+=1;continue}if(H.has(s)){n[s]=!0;continue}throw new a(`Unknown option: ${s}`)}return{flags:n,positional:t}}function Y(e,t){const n=e["--api-key"]??t.HYPERSCALE_API_KEY;if(!n)throw new a("No API key. Set HYPERSCALE_API_KEY, or pass --api-key. Request access at https://hyperscale0.ai/request-access.");const r=e["--environment"]??t.HYPERSCALE_ENVIRONMENT??k;if(r!=="sandbox"&&r!=="live")throw new a(`Unknown environment: ${r}. Use sandbox or live.`);const s=(e["--base-url"]??t.HYPERSCALE_BASE_URL??E).replace(/\/+$/,"");return{apiKey:n,baseUrl:s,environment:r}}async function N(e,t){try{const n=await fetch(t,{headers:{accept:"application/json",authorization:`Bearer ${e.apiKey}`,"x-hyperscale-environment":e.environment},signal:AbortSignal.timeout(I),redirect:"manual"});if(n.status>=300&&n.status<400)throw new a(`${t} redirected, so the key was not sent on. Point --base-url at the origin the API answers on; the usual cause is http:// where it serves https://.`);return{response:n,text:J(await n.text())}}catch(n){throw n instanceof a?n:new a(`Could not reach ${t}: ${n.message}`)}}async function V(e){const{response:t,text:n}=await N(e,`${e.baseUrl}/v1/llms.txt`);if(!t.ok)throw R(t,n,[e.apiKey]);const r=/^# (.+)$/m.exec(n),s=/^## Operations \((\d+)\)$/m.exec(n),o=/^- Auth: \S+ \(secret via (\S+)\)$/m.exec(n);if(!r||!s||!o)throw new Error("The product document is not in the expected format; upgrade the launcher.");const i=o[1];if(!/^HYPERSCALE_[A-Z0-9_]*$/.test(i))throw new a(`The product document names an invalid auth environment variable (${i}); refusing to scaffold.`);const c=[],d=/^- ([A-Z]+) (\S+) · (\S+) \((\S+); idempotency (\S+)\)$/gm;for(const u of n.matchAll(d))c.push({method:u[1],operationId:u[4],path:u[2]});const h=Number(s[1]);if(c.length!==h)throw new Error(`The product document declares ${h} operations but ${c.length} parsed; upgrade the launcher.`);const l=new Map,x=/^ {2}\d+\. (\S+) \(([^)]+)\)$/gm;for(const u of n.matchAll(x)){const y=u[1];if(!/^[A-Za-z_$][\w$]*$/.test(y))throw new a(`The product document names an invalid SDK function (${y}); refusing to scaffold.`);const[v,b]=u[2].split("; ");b!=="gap"&&!l.has(v)&&l.set(v,y)}const w=/^- Package: (.+)$/m.exec(n),$=/^- Registry: (\S+)$/m.exec(n);if(!w||!$)throw new a("This Product has no hosted SDK yet. Build it in the composer, then rerun.");const m=w[1].trim();if(!/^@hyperscale\/[a-z0-9][a-z0-9._-]*$/.test(m))throw new a(`The product document names an invalid SDK package (${m}); refusing to scaffold.`);const f=$[1].replace(/\/+$/,"");if(B(f)!==new URL(e.baseUrl).origin)throw new a(`The product document names a registry on another origin (${f}); refusing to scaffold.`);return{apiKeyEnvVar:i,operations:c,packageName:m,registryUrl:f,sdkFunctionByOperationId:l,title:r[1].trim()}}function J(e){return e.replace(/\p{Cc}/gu,t=>`	
+\r`.includes(t)?t:"")}function B(e){try{return new URL(e).origin}catch{return null}}async function M(e,t){const n=encodeURIComponent(t.packageName).replace("%40","@"),{response:r,text:s}=await N(e,`${t.registryUrl}/${n}`);if(!r.ok)throw R(r,s,[e.apiKey]);let o;try{o=JSON.parse(s)["dist-tags"]?.latest}catch{o=void 0}if(typeof o!="string")throw new a(`The registry packument for ${t.packageName} names no latest version; upgrade the launcher.`);if(!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(o))throw new a(`The registry packument for ${t.packageName} names ${o} as its latest version, which is not a version; refusing to scaffold.`);return o}function _(e,t){let n=e;for(const r of t)typeof r=="string"&&r.length>0&&(n=n.replaceAll(r,"[redacted]"));return n}function R(e,t,n=[]){let r=_(t.trim(),n);try{const s=JSON.parse(t);s&&s.error&&typeof s.error.message=="string"&&(r=_(`${s.error.code}: ${s.error.message}`,n))}catch{}return new a(`HTTP ${e.status}${r?` \xB7 ${r}`:""}`)}function g(e){const t=e.operations.find(n=>n.method==="GET"&&!n.path.includes("{")&&e.sdkFunctionByOperationId.has(n.operationId));if(t)return e.sdkFunctionByOperationId.get(t.operationId)}function z(e,t){const n=`// Generated by @hyperscale0/create for ${e.title}.
 // Run with: npm run hello (reads ${e.apiKeyEnvVar} from .env)
 import { createHyperscaleSdk } from ${JSON.stringify(e.packageName)};
 
@@ -41,11 +42,11 @@ const client = createHyperscaleSdk({
   ...(process.env.HYPERSCALE_BASE_URL
     ? { baseUrl: process.env.HYPERSCALE_BASE_URL }
     : {}),
-});`,r=R(e);if(!r){const s=`SDK client ready for ${e.title}.`,o=`node_modules/${e.packageName}/README.md`;return`${n}
+});`,r=g(e);if(!r){const s=`SDK client ready for ${e.title}.`,o=`node_modules/${e.packageName}/README.md`;return`${n}
 
 console.log(${JSON.stringify(s)});
 console.log(
-  "This product has no parameterless read; see the first-call example in",
+  "No callable parameterless SDK read was selected; see the first-call example in",
   ${JSON.stringify(o)},
 );
 `}return`${n}
@@ -56,13 +57,13 @@ if (result.error) {
   process.exit(1);
 }
 console.log(JSON.stringify(result.data, null, 2));
-`}function z(e){const t=new URL(e.registryUrl),n=t.pathname.endsWith("/")?t.pathname:`${t.pathname}/`;return`@hyperscale:registry=${e.registryUrl}
+`}function q(e){const t=new URL(e.registryUrl),n=t.pathname.endsWith("/")?t.pathname:`${t.pathname}/`;return`@hyperscale:registry=${e.registryUrl}
 //${t.host}${n}:_authToken=\${${e.apiKeyEnvVar}}
 ignore-scripts=true
-`}function q(e,t){return`${e.apiKeyEnvVar}=${t.apiKey}
+`}function G(e,t){return`${e.apiKeyEnvVar}=${t.apiKey}
 HYPERSCALE_BASE_URL=${t.baseUrl}
-`}function G(e){return K(v(e)).toLowerCase().replace(/[^a-z0-9._-]+/g,"-").replace(/^[-._]+/,"")||k}function W(e,t,n){return`${JSON.stringify({name:G(e),version:"0.0.0",private:!0,type:"module",scripts:{hello:"node --env-file=.env hello.mjs"},engines:{node:">=20.6"},dependencies:{[t.packageName]:n}},null,2)}
-`}function Z(e,t){return`# ${e.title}
+`}function W(e){return O(S(e)).toLowerCase().replace(/[^a-z0-9._-]+/g,"-").replace(/^[-._]+/,"")||A}function Z(e,t,n){return`${JSON.stringify({name:W(e),version:"0.0.0",private:!0,type:"module",scripts:{hello:"node --env-file=.env hello.mjs"},engines:{node:">=20.6"},dependencies:{[t.packageName]:n}},null,2)}
+`}function Q(e,t){const n=g(e)?"makes the product's first read call through the SDK":"constructs the SDK client and points to its tailored first-call example";return`# ${e.title}
 
 A minimal project wired to the hosted Hyperscale SDK for this product.
 
@@ -72,7 +73,7 @@ A minimal project wired to the hosted Hyperscale SDK for this product.
   reads the key from \`${e.apiKeyEnvVar}\`.
 - \`.env\` carries the key and the API host this project was created with. It
   is gitignored; rotate the key from the Developers desk whenever you need to.
-- \`hello.mjs\` makes the product's first read call through the SDK.
+- \`hello.mjs\` ${n}.
 
 ## Run
 
@@ -90,8 +91,9 @@ bunx @hyperscale0/cli ops list
 \`\`\`
 
 Needs Node 20.6 or newer (\`--env-file\`).
-`}function Q(e,t,n,r){return[{path:".env",contents:q(t,n)},{path:".gitignore",contents:`node_modules/
+`}function X(e,t,n,r){return[{path:".gitignore",contents:`node_modules/
 .env
-`},{path:".npmrc",contents:z(t)},{path:"README.md",contents:Z(t,r)},{path:"hello.mjs",contents:M(t,n.environment)},{path:"package.json",contents:W(e,t,r)}]}function X(e,t){const n=v(e);if(x(n)&&T(n).length>0)throw new a(`${e} already exists and is not empty. Pick a new directory.`);P(n,{recursive:!0});for(const r of t)L(O(n,r.path),r.contents);return n}function ee(e,t,n){return new Promise((r,s)=>{const o=b("npm",["install","--no-audit","--no-fund","--ignore-scripts"],{cwd:e,env:{...process.env,[t.apiKeyEnvVar]:n.apiKey},stdio:["ignore",2,2]});o.on("error",i=>{s(new a(`npm install could not start: ${i.message}. The project is written; fix the cause and run npm install in it.`))}),o.on("exit",i=>{if(i===0){r();return}s(new a(`npm install failed with exit code ${i}. The project is written; fix the cause and run npm install in it.`))})})}function p(e){process.stdout.write(`${e}
-`)}async function ne(){const{readFileSync:e}=await import("node:fs");return JSON.parse(e(new URL("./package.json",import.meta.url),"utf8")).version}async function te(e,t){const{flags:n,positional:r}=H(e);if(n["--version"])return p(await ne()),0;if(n["--help"])return process.stdout.write(C),0;if(r.length>1)throw new a("At most one directory argument is allowed.");const s=r[0]??k,o=Y(n,t),i=await F(o),c=await J(o,i),d=X(s,Q(s,i,o,c)),h=!n["--no-install"];h&&await ee(d,i,o);const l=R(i);return n["--json"]?(p(JSON.stringify({baseUrl:o.baseUrl,directory:d,environment:o.environment,helloOperation:l??null,installed:h,packageName:i.packageName,product:i.title,version:c},null,2)),0):(p(`Created ${s} for ${i.title}.`),p(""),p(`  ${i.packageName}@${c} (${o.environment})`),h||p("  npm install"),p(l?`  npm run hello   calls ${l}`:"  npm run hello   constructs the client; see README.md for the first call"),0)}te(process.argv.slice(2),process.env).then(e=>{process.exitCode=e},e=>{e instanceof a?process.stderr.write(`${e.message}
-`):console.error(e),process.exitCode=1});
+`},{path:".env",contents:G(t,n),mode:384},{path:".npmrc",contents:q(t)},{path:"README.md",contents:Q(t,r)},{path:"hello.mjs",contents:z(t,n.environment)},{path:"package.json",contents:Z(e,t,r)}]}function ee(e,t){const n=S(e);if(K(n)&&T(n).length>0)throw new a(`${e} already exists and is not empty. Pick a new directory.`);P(n,{recursive:!0});for(const r of t)L(D(n,r.path),r.contents,r.mode?{mode:r.mode}:{});return n}function ne(e,t,n,r){return new Promise((s,o)=>{const i=U("npm",["install","--no-audit","--no-fund","--ignore-scripts","--registry",t.registryUrl,"--prefer-online","--offline=false"],{cwd:e,env:{...process.env,[t.apiKeyEnvVar]:n.apiKey},stdio:r?["ignore","ignore","ignore"]:["ignore",2,2]});i.on("error",c=>{o(new a(`npm install could not start: ${c.message}. The project is written; fix the cause and run npm install in it.`))}),i.on("exit",c=>{if(c===0){s();return}o(new a(`npm install failed with exit code ${c}. The project is written; fix the cause and run npm install in it.`))})})}function p(e){process.stdout.write(`${e}
+`)}async function te(){const{readFileSync:e}=await import("node:fs");return JSON.parse(e(new URL("./package.json",import.meta.url),"utf8")).version}async function re(e,t){const{flags:n,positional:r}=F(e);if(n["--version"])return p(await te()),0;if(n["--help"])return process.stdout.write(C),0;if(r.length>1)throw new a("At most one directory argument is allowed.");const s=r[0]??A,o=Y(n,t),i=await V(o),c=await M(o,i),d=ee(s,X(s,i,o,c)),h=!n["--no-install"];h&&await ne(d,i,o,n["--json"]);const l=g(i);return n["--json"]?(p(JSON.stringify({baseUrl:o.baseUrl,directory:d,environment:o.environment,helloOperation:l??null,installed:h,packageName:i.packageName,product:i.title,version:c},null,2)),0):(p(`Created ${s} for ${i.title}.`),p(""),p(`  ${i.packageName}@${c} (${o.environment})`),h||p("  npm install"),p(l?`  npm run hello   calls ${l}`:"  npm run hello   constructs the client; see README.md for the first call"),0)}function se(e,t){if(!t.includes("--json")){e instanceof a?process.stderr.write(`${e.message}
+`):console.error(e);return}const n=e instanceof a;process.stderr.write(`${JSON.stringify({error:{code:n?"user_error":"internal_error",message:n?e.message:"The launcher failed unexpectedly.",fix:n?'Follow the message, or run "bunx @hyperscale0/create --help" for option usage.':"Report the failure without including credentials."}})}
+`)}re(process.argv.slice(2),process.env).then(e=>{process.exitCode=e},e=>{se(e,process.argv.slice(2)),process.exitCode=1});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperscale0/create",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "The Hyperscale project launcher: scaffold a minimal project wired to one Product's hosted SDK.",
   "license": "LicenseRef-Hyperscale-Proprietary",
   "author": "Hyperscale LLC",