@pylonsync/create-pylon 0.22.69 → 0.22.70

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -22,12 +22,14 @@
22
22
  */
23
23
 
24
24
  import {
25
+ copyFileSync,
25
26
  cpSync,
26
27
  existsSync,
27
28
  mkdirSync,
28
29
  readFileSync,
29
30
  readdirSync,
30
31
  statSync,
32
+ symlinkSync,
31
33
  writeFileSync,
32
34
  renameSync,
33
35
  } from "node:fs";
@@ -249,7 +251,9 @@ const resolveTemplate = (name) =>
249
251
  // ---------------------------------------------------------------------------
250
252
 
251
253
  const args = argv.slice(2);
252
- let projectName = args.find((a) => !a.startsWith("--"));
254
+
255
+ // Flags that take a value. `--flag value` and `--flag=value` are both accepted.
256
+ const VALUE_FLAGS = ["--template", "--platforms"];
253
257
 
254
258
  const flags = {
255
259
  pm: pickValue(args, "--bun", "--pnpm", "--yarn", "--npm")?.replace(/^--/, ""),
@@ -257,9 +261,8 @@ const flags = {
257
261
  platforms: takeValue(args, "--platforms"),
258
262
  skipInstall: args.includes("--skip-install"),
259
263
  // --skill / --no-skill: install the Pylon skill into the new project via
260
- // `npx skills add pylonsync/pylon-skills` — the skills.sh CLI detects the
261
- // coding agent (Claude Code / Codex / Cursor) and drops the skill from the
262
- // public pylon-skills repo, which each release copies from skills/. undefined => prompt (default yes).
264
+ // the skills.sh CLI, from the public pylon-skills repo, which each release
265
+ // copies from skills/. undefined => prompt (default yes).
263
266
  skill: args.includes("--skill")
264
267
  ? true
265
268
  : args.includes("--no-skill")
@@ -268,6 +271,23 @@ const flags = {
268
271
  help: args.includes("--help") || args.includes("-h"),
269
272
  };
270
273
 
274
+ // Arguments that are neither a flag nor the value of a value flag.
275
+ const positionals = args.filter(
276
+ (a, i) =>
277
+ !a.startsWith("-") && !(i > 0 && VALUE_FLAGS.includes(args[i - 1])),
278
+ );
279
+
280
+ recoverNpmSwallowedFlags(flags, positionals, process.env);
281
+
282
+ let projectName = positionals.shift();
283
+ if (positionals.length > 0) {
284
+ console.error(
285
+ `\nError: unexpected argument(s): ${positionals.join(" ")}\n` +
286
+ `Usage: npm create @pylonsync/pylon@latest [name] -- [options]\n`,
287
+ );
288
+ exit(1);
289
+ }
290
+
271
291
  function takeValue(arr, name) {
272
292
  const flagWithEq = arr.find((a) => a.startsWith(name + "="));
273
293
  if (flagWithEq) return flagWithEq.slice(name.length + 1);
@@ -285,13 +305,79 @@ function pickValue(arr, ...candidates) {
285
305
  return undefined;
286
306
  }
287
307
 
308
+ /**
309
+ * Restore the flags npm consumed.
310
+ *
311
+ * `npm create pkg name --template saas` (no `--` separator) does not pass
312
+ * `--template` to this script. npm 7+ parses it as its own boolean option,
313
+ * sets `npm_config_template=true`, and passes `saas` as a plain positional.
314
+ * `--template=saas` arrives as `npm_config_template=saas` with no positional.
315
+ * Boolean flags arrive as `npm_config_<name>=true`, and `--no-skill` as an
316
+ * empty `npm_config_skill`.
317
+ *
318
+ * A value flag whose value cannot be identified is an error. The scaffold
319
+ * does not continue on a default template the caller did not ask for.
320
+ */
321
+ function recoverNpmSwallowedFlags(flags, positionals, env) {
322
+ if (!(env.npm_config_user_agent ?? "").startsWith("npm/")) return;
323
+
324
+ const isTemplate = (v) =>
325
+ TEMPLATES_AVAILABLE.includes(resolveTemplate(v.toLowerCase()));
326
+ const isPlatformList = (v) =>
327
+ v
328
+ .split(",")
329
+ .every((p) => PLATFORMS_AVAILABLE.includes(p.trim().toLowerCase()));
330
+
331
+ const recoverValue = (key, accepts, valid) => {
332
+ const raw = env[`npm_config_${key}`];
333
+ if (flags[key] !== undefined || raw === undefined || raw === "") return;
334
+ if (raw !== "true") {
335
+ flags[key] = raw;
336
+ return;
337
+ }
338
+ // npm does not say which positional was the value. Exactly one must
339
+ // qualify: with two, either could be the project name.
340
+ const matches = positionals.filter(accepts);
341
+ if (matches.length === 1) {
342
+ flags[key] = positionals.splice(positionals.indexOf(matches[0]), 1)[0];
343
+ return;
344
+ }
345
+ const problem =
346
+ matches.length === 0
347
+ ? `its value is not a known ${key} value`
348
+ : `more than one argument is a ${key} value (${matches.join(", ")})`;
349
+ console.error(
350
+ `\nError: npm consumed --${key} and ${problem}.\n` +
351
+ `Valid: ${valid.join(", ")}\n` +
352
+ `Put "--" before the options so npm passes them on:\n` +
353
+ ` npm create @pylonsync/pylon@latest my-app -- --${key} <value>\n`,
354
+ );
355
+ exit(1);
356
+ };
357
+ recoverValue("template", isTemplate, TEMPLATES_AVAILABLE);
358
+ recoverValue("platforms", isPlatformList, PLATFORMS_AVAILABLE);
359
+
360
+ if (!flags.pm) {
361
+ flags.pm = ["bun", "pnpm", "yarn", "npm"].find(
362
+ (pm) => env[`npm_config_${pm}`] === "true",
363
+ );
364
+ }
365
+ if (env.npm_config_skip_install === "true") flags.skipInstall = true;
366
+ if (flags.skill === undefined && env.npm_config_skill !== undefined) {
367
+ flags.skill = env.npm_config_skill === "true";
368
+ }
369
+ if (env.npm_config_help === "true") flags.help = true;
370
+ }
371
+
288
372
  if (flags.help) {
289
373
  const tmplLines = Object.entries(TEMPLATE_REGISTRY).map(
290
374
  ([k, v]) =>
291
375
  ` ${k.padEnd(10)} ${v.blurb} (${v.unified ? "single app" : v.platforms.join(", ")})`,
292
376
  );
293
377
  process.stdout.write(`
294
- Usage: npm create @pylonsync/pylon [name] [options]
378
+ Usage: npm create @pylonsync/pylon@latest [name] -- [options]
379
+
380
+ npm needs the "--" before the options. bun, pnpm and yarn do not.
295
381
 
296
382
  --template <t> ${TEMPLATES_AVAILABLE.join(" | ")}
297
383
  ${tmplLines.join("\n")}
@@ -301,29 +387,30 @@ ${tmplLines.join("\n")}
301
387
  except consumer, where ios,expo scaffolds native apps on a shared backend
302
388
  --bun|--pnpm|--yarn|--npm
303
389
  --skip-install scaffold only, don't run install
390
+ --skill | --no-skill add the Pylon skill to the project for Claude Code, Codex and Cursor
304
391
 
305
392
  Examples:
306
- npm create @pylonsync/pylon my-app # default — the smallest SSR app that runs
307
- npm create @pylonsync/pylon my-app --template saas # building a product? start here: landing + orgs + billing
308
- npm create @pylonsync/pylon my-app --template mobile # App Store-ready Expo app + backend: onboarding, sign-in, paywall
309
- npm create @pylonsync/pylon my-app --template consumer --platforms ios,expo # photo app: SwiftUI + Expo on one backend
310
- npm create @pylonsync/pylon my-app --template todo # live, optimistic todo (SSR, one port)
311
- npm create @pylonsync/pylon my-app --template chat # realtime live chat room
312
- npm create @pylonsync/pylon my-app --template waitlist # coming-soon landing + live signup counter
313
- npm create @pylonsync/pylon my-app --template local-service # appointment business + live booking availability
314
- npm create @pylonsync/pylon my-app --template restaurant # restaurant menu + live reservation availability
315
- npm create @pylonsync/pylon my-app --template creator # personal brand + live newsletter subscriber count
316
- npm create @pylonsync/pylon my-app --template shop # DTC store + live inventory
317
- npm create @pylonsync/pylon my-app --template agency # studio/agency + live project availability
318
- npm create @pylonsync/pylon my-app --template marketplace # two-sided marketplace + realtime offers
319
- npm create @pylonsync/pylon my-app --template directory # searchable directory + facets + live upvotes
320
- npm create @pylonsync/pylon my-app --template crm # sales CRM — live pipeline board, ⌘K, activity timeline
321
- npm create @pylonsync/pylon my-app --template helpdesk # support inbox — SLA triage, shared threads, internal notes
322
- npm create @pylonsync/pylon my-app --template invoices # invoicing — line items, payments, derived ageing
323
- npm create @pylonsync/pylon my-app --template inventory # stock control — append-only ledger, reorder flags
324
- npm create @pylonsync/pylon my-app --template projects # client delivery — task board, time tracking, budgets
325
- npm create @pylonsync/pylon my-app --template ai-chat # streaming LLM chat + synced history
326
- npm create @pylonsync/pylon my-app --template ai-studio # generative media studio + live gallery
393
+ npm create @pylonsync/pylon@latest my-app # default — the smallest SSR app that runs
394
+ npm create @pylonsync/pylon@latest my-app -- --template saas # building a product? start here: landing + orgs + billing
395
+ npm create @pylonsync/pylon@latest my-app -- --template mobile # App Store-ready Expo app + backend: onboarding, sign-in, paywall
396
+ npm create @pylonsync/pylon@latest my-app -- --template consumer --platforms ios,expo # photo app: SwiftUI + Expo on one backend
397
+ npm create @pylonsync/pylon@latest my-app -- --template todo # live, optimistic todo (SSR, one port)
398
+ npm create @pylonsync/pylon@latest my-app -- --template chat # realtime live chat room
399
+ npm create @pylonsync/pylon@latest my-app -- --template waitlist # coming-soon landing + live signup counter
400
+ npm create @pylonsync/pylon@latest my-app -- --template local-service # appointment business + live booking availability
401
+ npm create @pylonsync/pylon@latest my-app -- --template restaurant # restaurant menu + live reservation availability
402
+ npm create @pylonsync/pylon@latest my-app -- --template creator # personal brand + live newsletter subscriber count
403
+ npm create @pylonsync/pylon@latest my-app -- --template shop # DTC store + live inventory
404
+ npm create @pylonsync/pylon@latest my-app -- --template agency # studio/agency + live project availability
405
+ npm create @pylonsync/pylon@latest my-app -- --template marketplace # two-sided marketplace + realtime offers
406
+ npm create @pylonsync/pylon@latest my-app -- --template directory # searchable directory + facets + live upvotes
407
+ npm create @pylonsync/pylon@latest my-app -- --template crm # sales CRM — live pipeline board, ⌘K, activity timeline
408
+ npm create @pylonsync/pylon@latest my-app -- --template helpdesk # support inbox — SLA triage, shared threads, internal notes
409
+ npm create @pylonsync/pylon@latest my-app -- --template invoices # invoicing — line items, payments, derived ageing
410
+ npm create @pylonsync/pylon@latest my-app -- --template inventory # stock control — append-only ledger, reorder flags
411
+ npm create @pylonsync/pylon@latest my-app -- --template projects # client delivery — task board, time tracking, budgets
412
+ npm create @pylonsync/pylon@latest my-app -- --template ai-chat # streaming LLM chat + synced history
413
+ npm create @pylonsync/pylon@latest my-app -- --template ai-studio # generative media studio + live gallery
327
414
  `);
328
415
  exit(0);
329
416
  }
@@ -435,8 +522,8 @@ if (flags.skill === undefined) {
435
522
  .toLowerCase();
436
523
  flags.skill = ans !== "n" && ans !== "no";
437
524
  } else {
438
- // Non-interactive: can't prompt. The actual install is TTY-gated below,
439
- // so this only controls whether the footer prints the one-liner hint.
525
+ // Non-interactive: no prompt. The skill file ships in this package, so
526
+ // adding it needs no network.
440
527
  flags.skill = true;
441
528
  }
442
529
  }
@@ -736,30 +823,70 @@ if (!flags.skipInstall) {
736
823
  // ---------------------------------------------------------------------------
737
824
  // Optional: install the Pylon skill into the project's coding agent.
738
825
  //
739
- // `npx skills add pylonsync/pylon-skills` (skills.sh) detects the installed
740
- // agent (Claude Code / Codex / Cursor) and drops the skill from the public
741
- // pylon-skills repo, which each release copies from this repo's skills/. We
742
- // only auto-run it when stdin is a TTY: the skills CLI prompts for scope and
743
- // agent, which would hang a non-interactive scaffold (CI, piped input). When
744
- // we can't run it, the footer prints the one-liner so the user can opt in.
826
+ // On a TTY the skills.sh CLI installs it from the public pylon-skills repo
827
+ // and asks which agents to install to. Without a TTY that prompt cancels the
828
+ // install, and the CLI needs git, which slim CI and container images do not
829
+ // have. So the package also carries the skill file, and the scaffolder writes
830
+ // it to .agents/skills/pylon (read by Codex, Cursor and the other agents that
831
+ // use that directory) with a link from .claude/skills/pylon for Claude Code.
832
+ // That is the same layout the CLI produces.
745
833
  // ---------------------------------------------------------------------------
746
834
 
747
835
  const SKILL_REPO = "pylonsync/pylon-skills";
748
836
  const SKILL_INSTALL_CMD = `npx skills add ${SKILL_REPO}`;
837
+ // skill/ is copied in when the package is published. A source checkout reads
838
+ // the canonical file.
839
+ const BUNDLED_SKILL = [
840
+ join(HERE, "..", "skill", "SKILL.md"),
841
+ join(HERE, "..", "..", "..", "skills", "pylon", "SKILL.md"),
842
+ ].find((p) => existsSync(p));
843
+
844
+ async function runSkillsCli(extraArgs) {
845
+ const { spawnSync } = await import("node:child_process");
846
+ const result = spawnSync(
847
+ "npx",
848
+ ["-y", "skills", "add", SKILL_REPO, ...extraArgs],
849
+ {
850
+ cwd: root,
851
+ stdio: stdin.isTTY ? "inherit" : ["ignore", "inherit", "inherit"],
852
+ shell: process.platform === "win32",
853
+ },
854
+ );
855
+ return result.status === 0;
856
+ }
857
+
858
+ function writeBundledSkill() {
859
+ if (!BUNDLED_SKILL) return false;
860
+ const dir = join(root, ".agents", "skills", "pylon");
861
+ mkdirSync(dir, { recursive: true });
862
+ copyFileSync(BUNDLED_SKILL, join(dir, "SKILL.md"));
863
+ const claudeSkills = join(root, ".claude", "skills");
864
+ const claudeLink = join(claudeSkills, "pylon");
865
+ mkdirSync(claudeSkills, { recursive: true });
866
+ if (!existsSync(claudeLink)) {
867
+ try {
868
+ symlinkSync(join("..", "..", ".agents", "skills", "pylon"), claudeLink, "dir");
869
+ } catch {
870
+ // Windows without the symlink privilege.
871
+ mkdirSync(claudeLink, { recursive: true });
872
+ copyFileSync(BUNDLED_SKILL, join(claudeLink, "SKILL.md"));
873
+ }
874
+ }
875
+ return true;
876
+ }
877
+
749
878
  let skillInstalled = false;
750
- if (flags.skill && stdin.isTTY) {
879
+ if (flags.skill) {
751
880
  console.log("\nAdding the Pylon skill to your coding agent...");
752
- const { spawnSync } = await import("node:child_process");
753
- const result = spawnSync("npx", ["-y", "skills", "add", SKILL_REPO], {
754
- cwd: root,
755
- stdio: "inherit",
756
- });
757
- skillInstalled = result.status === 0;
758
- if (!skillInstalled) {
759
- console.warn(
760
- `\nCouldn't add the skill automatically. Run it yourself anytime:\n ${SKILL_INSTALL_CMD}\n`,
761
- );
881
+ if (stdin.isTTY) skillInstalled = await runSkillsCli([]);
882
+ if (!skillInstalled) skillInstalled = writeBundledSkill();
883
+ if (!skillInstalled && !stdin.isTTY) {
884
+ skillInstalled = await runSkillsCli([
885
+ "-y",
886
+ ...["claude-code", "codex", "cursor"].flatMap((agent) => ["-a", agent]),
887
+ ]);
762
888
  }
889
+ if (!skillInstalled) console.warn("\nThe skill was not added.");
763
890
  }
764
891
 
765
892
  // ---------------------------------------------------------------------------
@@ -810,7 +937,7 @@ if (platforms.includes("expo"))
810
937
  const skillLine = skillInstalled
811
938
  ? "\nPylon skill added to your coding agent (Claude Code / Codex / Cursor).\n"
812
939
  : flags.skill
813
- ? `\nAdd the Pylon skill to your coding agent:\n ${SKILL_INSTALL_CMD}\n`
940
+ ? `\nAdd the Pylon skill to your coding agent:\n cd ${projectName} && ${SKILL_INSTALL_CMD}\n`
814
941
  : "";
815
942
 
816
943
  // Surface the in-repo operating manual. Pylon is agent-native: a coding agent
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pylonsync/create-pylon",
3
- "version": "0.22.69",
3
+ "version": "0.22.70",
4
4
  "description": "Scaffold a new Pylon app — realtime backend + web/mobile/expo frontends in one command. Run via `npm create @pylonsync/pylon@latest`.",
5
5
  "publishConfig": {
6
6
  "access": "public"
@@ -15,6 +15,7 @@
15
15
  "files": [
16
16
  "bin",
17
17
  "templates",
18
+ "skill",
18
19
  "LICENSE"
19
20
  ],
20
21
  "engines": {