create-satin 0.0.0-stage → 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satin 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.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# create-satin
 
-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.
+Create a Vite + React app for the iPhone Home Screen runtime.
+
+After the beta is published:
+
+```sh
+npm create satin@beta -- my-app --yes --name "My App" --id my-app
+# or
+pnpm create satin@beta my-app --yes --name "My App" --id my-app
+```
+
+Run `create-satin --help` for all flags, including launch colours and a local
+Satin tarball override. The command copies a bundled template, refuses to
+overwrite a nonempty directory, and leaves installation to you. It has no
+runtime dependencies. Node 22.12+ on the 22.x line, or Node 24+, is required.
+
+Quote destination paths containing spaces. The folder keeps its requested name;
+the npm package name and default app ID use a lowercase name with other characters
+replaced by hyphens and edge hyphens removed. An empty result uses `my-app`.
+For example, `"My App #%?"` creates that folder with package name `my-app` and ID `my-app`.
+
+`--icon` copies one square PNG source; the build derives the install icon sizes.
+`--accent` writes `appearance.tint`; Satin applies the tint at runtime. Without it no tint is written and the app uses the system blue.
+Launch colours write the light/dark `appearance` backgrounds. If a bundled
+template cannot apply a flag, the command fails before creating the destination.
+
+The template has Home and Settings tabs with independent navigation stacks, a
+saved-item detail route and a Your data route that exports JSON. It uses useQuery
+and useRecord for local data. It does not import data. Add validation, a preview,
+backup and confirmation before building an import flow.
+
+The app includes README.md, AGENTS.md, IOS-DESIGN.md and GETTING-STARTED.md.
+The packaged API reference documents each export and its limitations.
+
+Maintainers edit `templates/basic/` in the repository. `npm run build` copies it
+into this package before packing, so the published CLI works outside the repo.
+
+Set `SATIN_DOCS_BASE_URL` when building or packing the CLI to choose where the
+generated `GETTING-STARTED.md` links resolve. It is an HTTP(S) repository-root
+URL containing both `docs/` and `packages/`; include the release revision for
+versioned source documentation. For example:
+
+```sh
+SATIN_DOCS_BASE_URL=https://docs.example.com/satin/v0.1.0-beta.0/ npm run build
+```
+
+The default uses the configured source repository at its default revision. Before publication,
+set the docs base URL to the chosen public repository and release revision.
+The build normalizes the trailing slash and rejects credentials, query strings,
+fragments and non-HTTP schemes. External service links and page anchors keep
+their original targets. This is a packaging option; app creators do not need to
+set it. Packaging checks every shipped template Markdown file, the generated
+guide and both package READMEs for private project-status language.

package/bin/create-satin.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { parseArgs } from 'node:util'
+
+const help = `Create a Satin app
+
+  npm create satin@beta -- my-app --yes
+  pnpm create satin@beta my-app --yes
+
+Options:
+  --name "My App"           Display name, default My Satin App
+  --id my-app               Stable app identity, default <directory name>
+  --background '#f2f2f7'     Light launch and app background
+  --dark-background '#000000' Dark launch and app background
+  --icon <file.png>         App icon, copied into the generated project
+  --accent '#007aff'         App tint colour (appearance.tint); omit for the system blue
+  --satin-package <spec>    Override dependency, e.g. /absolute/satin.tgz
+  --yes                     Use defaults for omitted answers
+  --help                    Show this help
+
+The destination must be absent or empty. No packages are installed automatically.
+`
+const hex = /^#[\da-f]{6}$/iu
+const jsString = value => JSON.stringify(value).replaceAll('<', '\\u003c')
+
+function packageNameForDirectory(directory) {
+  return (
+    basename(resolve(directory))
+      .toLowerCase()
+      .replace(/[^a-z0-9-]+/gu, '-')
+      .replace(/^-+|-+$/gu, '') || 'my-app'
+  )
+}
+
+function appIdForDirectory(directory) {
+  const name = packageNameForDirectory(directory)
+  return /^[a-z]/u.test(name) ? name : `app-${name}`
+}
+
+function replaceRequired(source, search, replacement, flag, expectedMatches = 1) {
+  const matches =
+    typeof search === 'string' ? source.split(search).length - 1 : source.match(search) ? 1 : 0
+  if (matches !== expectedMatches) {
+    throw new Error(
+      `Cannot apply --${flag}: bundled src/app.ts expected ${expectedMatches} match(es) for ${search}, found ${matches}.`,
+    )
+  }
+  return typeof search === 'string'
+    ? source.replaceAll(search, replacement)
+    : source.replace(search, replacement)
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      name: { type: 'string' },
+      id: { type: 'string' },
+      background: { type: 'string', default: '#f2f2f7' },
+      'dark-background': { type: 'string', default: '#000000' },
+      icon: { type: 'string' },
+      accent: { type: 'string' },
+      'satin-package': { type: 'string' },
+      yes: { type: 'boolean', short: 'y' },
+      help: { type: 'boolean', short: 'h' },
+    },
+  })
+  if (values.help) {
+    console.log(help)
+    return
+  }
+  if (positionals.length > 1) throw new Error('Provide one destination directory.')
+  let destination = positionals[0]
+  let name = values.name
+  let id = values.id
+  if (!values.yes && process.stdin.isTTY && process.stdout.isTTY) {
+    const prompt = createInterface({ input: process.stdin, output: process.stdout })
+    try {
+      destination ??= (await prompt.question('Directory [my-app]: ')) || 'my-app'
+      name ??= (await prompt.question('App name [My Satin App]: ')) || 'My Satin App'
+      id ??= (await prompt.question(`App ID [${appIdForDirectory(destination)}]: `)) || undefined
+    } finally {
+      prompt.close()
+    }
+  }
+  destination ??= 'my-app'
+  const target = resolve(destination)
+  const packageName = packageNameForDirectory(target)
+  name ??= 'My Satin App'
+  id ??= appIdForDirectory(destination)
+  if (packageName.length > 214) {
+    throw new Error('Package name derived from the directory must be at most 214 characters.')
+  }
+  if (
+    !name.trim() ||
+    name !== name.trim() ||
+    name.length > 80 ||
+    [...name].some(char => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)
+  ) {
+    throw new Error('App name must be 1–80 characters, without padding or control characters.')
+  }
+  if (!/^[a-z][a-z0-9-]*$/u.test(id))
+    throw new Error('App ID must be a lowercase slug such as my-app.')
+  for (const key of ['background', 'dark-background', 'accent']) {
+    // Without --accent the app keeps the system blue, which differs between light and dark.
+    if (key === 'accent' && values.accent === undefined) continue
+    if (!hex.test(values[key])) throw new Error(`--${key} must be a six-digit hex colour.`)
+  }
+  let suppliedIcon
+  if (values.icon) {
+    const bytes = await readFile(resolve(values.icon))
+    if (bytes.length < 24 || bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a')
+      throw new Error('--icon must be a PNG file.')
+    suppliedIcon = { bytes, width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) }
+    if (!suppliedIcon.width || suppliedIcon.width !== suppliedIcon.height)
+      throw new Error('--icon must be square.')
+  }
+  if (values['satin-package'] !== undefined && !values['satin-package'].trim())
+    throw new Error('--satin-package cannot be empty.')
+  try {
+    if ((await readdir(target)).length)
+      throw new Error('Destination is not empty; no files were changed.')
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+
+  const template = resolve(import.meta.dirname, '../template')
+  const read = path => readFile(resolve(template, path), 'utf8')
+  const write = (path, text) => writeFile(resolve(target, path), text)
+  const pkg = JSON.parse(await read('package.json'))
+  pkg.name = packageName
+  if (values['satin-package']) {
+    if (!pkg.dependencies?.['@satinhq/kit']) {
+      throw new Error('Cannot apply --satin-package: bundled package.json has no satin dependency.')
+    }
+    pkg.dependencies['@satinhq/kit'] = values['satin-package']
+  }
+  // Identity and both appearances have one definition. Encode literals safely.
+  let definition = await read('src/app.ts')
+  const replacements = [
+    ["id: 'my-satin-app'", `id: ${jsString(id)}`, 'id', 1],
+    ["'My Satin App'", jsString(name), 'name', 2],
+    ["background: '#f2f2f7'", `background: ${jsString(values.background)}`, 'background', 1],
+    [
+      "background: '#000000'",
+      `background: ${jsString(values['dark-background'])}`,
+      'dark-background',
+      1,
+    ],
+  ]
+  if (values.accent !== undefined) {
+    replacements.push([
+      'appearance: {',
+      `appearance: {\n    tint: ${jsString(values.accent)},`,
+      'accent',
+      1,
+    ])
+  }
+  for (const [search, , flag, count] of replacements) {
+    replaceRequired(definition, search, search, flag, count)
+  }
+  // Substitute in one pass so user text cannot become another template match.
+  const replacementByToken = new Map(
+    replacements.map(([search, replacement]) => [search, replacement]),
+  )
+  const tokenPattern = replacements
+    .map(([search]) => search.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'))
+    .join('|')
+  definition = definition.replace(new RegExp(tokenPattern, 'gu'), token =>
+    replacementByToken.get(token),
+  )
+  // Check every substitution before creating any destination files.
+  await mkdir(target, { recursive: true })
+  for (const entry of await readdir(template)) {
+    await cp(resolve(template, entry), resolve(target, entry), {
+      recursive: true,
+      force: false,
+      errorOnExist: true,
+    })
+  }
+  await rename(resolve(target, '_gitignore'), resolve(target, '.gitignore'))
+  await write('package.json', `${JSON.stringify(pkg, null, 2)}\n`)
+  if (suppliedIcon) {
+    await writeFile(resolve(target, 'public/icon-source.png'), suppliedIcon.bytes)
+  }
+  await write('src/app.ts', definition)
+  console.log(
+    `Created ${name} in ${target}.\n\nNext, in that directory:\n  npm install\n  npm run dev\n\nOpen the printed address at /app/ in iPhone or iPad Safari, or iOS Simulator Safari.\nFor a physical device, use a reachable trusted HTTPS address. See README.md for installed builds.`,
+  )
+}
+
+main().catch(error => {
+  console.error(`create-satin: ${error.message}`)
+  process.exitCode = 1
+})

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "create-satin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.1",
+  "description": "Create a Satin iPhone Home Screen app.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": "^22.12.0 || >=24.0.0"
+  },
+  "bin": {
+    "create-satin": "./bin/create-satin.mjs"
+  },
+  "files": [
+    "bin",
+    "template",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/satinhq/satin.git",
+    "directory": "packages/create-pwakit"
+  },
+  "devDependencies": {
+    "oxlint": "^1.79.0"
+  },
+  "homepage": "https://satin.build",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "node --check bin/create-satin.mjs && node --check scripts/build.mjs",
+    "lint": "oxlint bin scripts test",
+    "test": "node --test test/*.test.mjs"
+  }
 }