@xrystal/core 3.52.5 → 3.52.7

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.
Files changed (40) hide show
  1. package/README.md +8 -2
  2. package/package.json +1 -1
  3. package/x/bin/commands/create.mjs +2 -4
  4. package/x/bin/commands/project-info.mjs +94 -0
  5. package/x/bin/commands/projects.mjs +1 -1
  6. package/x/bin/commands/sync.mjs +67 -101
  7. package/x/bin/commands/tmp.mjs +12 -9
  8. package/x/bin/helpers/.generated/seed-from-tmp.mjs +1 -0
  9. package/x/bin/helpers/.generated/tmp-schema.mjs +1 -0
  10. package/x/bin/helpers/.generated/workspace.mjs +3 -2
  11. package/x/bin/helpers/.generated/xrystal-home-registry.mjs +192 -44
  12. package/x/bin/helpers/cli-help.mjs +43 -13
  13. package/x/bin/helpers/project-context.mjs +147 -0
  14. package/x/bin/helpers/scaffold-service.mjs +2 -3
  15. package/x/bin/helpers/sync-project.mjs +76 -0
  16. package/x/bin/helpers/sync-scope.mjs +71 -0
  17. package/x/bin/helpers/tmp-config.mjs +25 -0
  18. package/x/bin/helpers/tmp-layout.mjs +2 -3
  19. package/x/bin/helpers/tmp-schema-version.mjs +46 -0
  20. package/x/bin/helpers/workspace-scaffold.mjs +4 -9
  21. package/x/bin/main-cli.js +10 -1
  22. package/x/dist/loader/kafka/index.js +7 -2
  23. package/x/dist/loader/logger/index.js +8 -6
  24. package/x/dist/loader/mongo/index.js +9 -0
  25. package/x/dist/loader/redis/index.js +9 -0
  26. package/x/dist/project/index.d.ts +1 -0
  27. package/x/dist/project/index.js +21 -14
  28. package/x/dist/utils/constants/defaults.json +1 -0
  29. package/x/dist/utils/helpers/loader-options/index.d.ts +5 -0
  30. package/x/dist/utils/helpers/loader-options/index.js +16 -0
  31. package/x/dist/utils/helpers/tmp/index.d.ts +1 -0
  32. package/x/dist/utils/helpers/tmp/index.js +1 -0
  33. package/x/dist/utils/helpers/tmp/loader-boot-plan.d.ts +10 -0
  34. package/x/dist/utils/helpers/tmp/loader-boot-plan.js +36 -0
  35. package/x/dist/utils/helpers/workspace/index.d.ts +1 -1
  36. package/x/dist/utils/helpers/workspace/index.js +2 -2
  37. package/x/templates/api-service/tmp.yml +7 -1
  38. package/x/templates/frontend/tmp.yml +61 -0
  39. package/x/tmp.yml +1 -1
  40. package/x/bin/helpers/tmp-end-version.mjs +0 -35
@@ -1,11 +1,11 @@
1
1
  // source/utils/helpers/xrystal-home/registry.ts
2
- import fs2 from "node:fs";
2
+ import fs3 from "node:fs";
3
3
  import os from "node:os";
4
- import path2 from "node:path";
4
+ import path3 from "node:path";
5
5
 
6
6
  // source/utils/helpers/workspace/index.ts
7
- import fs from "node:fs";
8
- import path from "node:path";
7
+ import fs2 from "node:fs";
8
+ import path2 from "node:path";
9
9
 
10
10
  // source/utils/models/enums/index.ts
11
11
  var GlobalTypeEnum;
@@ -14,6 +14,167 @@ var GlobalTypeEnum;
14
14
  GlobalTypeEnum2["API_SERVICE"] = "api-service";
15
15
  GlobalTypeEnum2["FRONTEND"] = "frontend";
16
16
  })(GlobalTypeEnum ||= {});
17
+ // source/utils/constants/defaults.json
18
+ var defaults_default = {
19
+ packageName: "@xrystal/core",
20
+ packageRootFolder: "x",
21
+ cliName: "xry",
22
+ cliBinNames: [
23
+ "xry"
24
+ ],
25
+ cliBinFile: "main-cli.js",
26
+ tmpBaseName: "tmp",
27
+ tmpExtension: ".yml",
28
+ tmpSchemaVersion: 1,
29
+ apiServiceTemplateRel: "x/templates/api-service/tmp.yml",
30
+ templateRepoUri: "https://github.com/xdloper/api-gpt-svc",
31
+ publicFolderName: "public",
32
+ kafkaLogsTopic: "log",
33
+ pathAliasKey: "@/*",
34
+ eslintRestrictedImportDepth: 2,
35
+ brand: {
36
+ primary: "xrystal",
37
+ secondary: "core",
38
+ tagline: "microservice runtime library",
39
+ capabilities: "loaders · tmp.yml · dto · i18n · multi-protocol · scaffold"
40
+ },
41
+ runtimes: {
42
+ bun: {
43
+ label: "Bun",
44
+ packageManager: "bun",
45
+ installCommand: "bun install",
46
+ scriptRunner: "bun run",
47
+ binRunner: "bun",
48
+ testRunner: "bun test",
49
+ tscBin: "bunx tsc",
50
+ esbuildBin: "bunx esbuild",
51
+ devInvoker: null
52
+ },
53
+ node: {
54
+ label: "Node.js",
55
+ packageManager: "npm",
56
+ installCommand: "npm install",
57
+ scriptRunner: "npm run",
58
+ binRunner: "node",
59
+ testRunner: "node --test",
60
+ tscBin: "npx tsc",
61
+ esbuildBin: "npx esbuild",
62
+ devInvoker: "npx"
63
+ }
64
+ },
65
+ bundlers: [
66
+ "auto",
67
+ "bun",
68
+ "tsc",
69
+ "esbuild"
70
+ ],
71
+ tmpWatchDefaults: {
72
+ intervalMs: 500,
73
+ minIntervalMs: 100,
74
+ maxIntervalMs: 1e4
75
+ },
76
+ buildDefaults: {
77
+ bundler: "auto",
78
+ tsconfig: "tsconfig.json",
79
+ typecheck: false,
80
+ tscLenient: true,
81
+ declarations: false,
82
+ sourcemap: false,
83
+ minify: false
84
+ }
85
+ };
86
+
87
+ // source/utils/helpers/tmp/seed-from-tmp.ts
88
+ import fs from "node:fs";
89
+ import path from "node:path";
90
+ import { fileURLToPath } from "node:url";
91
+ import yaml from "yaml";
92
+
93
+ // source/utils/helpers/tmp/path-normalize.ts
94
+ function normalizeRootFolder(value, fallback) {
95
+ if (typeof value !== "string" || !value.trim())
96
+ return fallback;
97
+ return value.trim().replace(/^\.\/+/, "");
98
+ }
99
+ function normalizeSourceFolder(value, fallback) {
100
+ if (typeof value !== "string" || !value.trim())
101
+ return fallback;
102
+ const trimmed = value.trim();
103
+ if (trimmed.startsWith("./") || trimmed.startsWith("../"))
104
+ return trimmed;
105
+ return `./${trimmed}`;
106
+ }
107
+
108
+ // source/utils/helpers/tmp/seed-from-tmp.ts
109
+ var here = path.dirname(fileURLToPath(import.meta.url));
110
+ var templateRel = defaults_default.apiServiceTemplateRel ?? "x/templates/api-service/tmp.yml";
111
+ function requireString(value, label) {
112
+ if (typeof value !== "string" || !value.trim()) {
113
+ throw new Error(`${defaults_default.packageName}: bundled template missing ${label}`);
114
+ }
115
+ return value.trim();
116
+ }
117
+ function readLayoutFromSpecial(special) {
118
+ const block = special && typeof special === "object" && !Array.isArray(special) ? special : {};
119
+ return {
120
+ tests: requireString(block.tests, "configs.global.paths.special.tests"),
121
+ environments: requireString(block.environments, "configs.global.paths.special.environments"),
122
+ dist: requireString(block.dist, "configs.global.paths.special.dist")
123
+ };
124
+ }
125
+ function findApiTemplate() {
126
+ const starts = [here, process.cwd()].map((value) => path.resolve(value));
127
+ for (const start of starts) {
128
+ let dir = start;
129
+ for (;; ) {
130
+ const candidate = path.join(dir, templateRel);
131
+ if (fs.existsSync(candidate))
132
+ return candidate;
133
+ const parent = path.dirname(dir);
134
+ if (parent === dir)
135
+ break;
136
+ dir = parent;
137
+ }
138
+ }
139
+ throw new Error(`${defaults_default.packageName}: api-service template not found (${templateRel})`);
140
+ }
141
+ function loadSeedFromBundledTmp(tmpFilePath) {
142
+ const file = tmpFilePath ?? findApiTemplate();
143
+ const doc = yaml.parse(fs.readFileSync(file, "utf8"));
144
+ const configs = doc?.configs && typeof doc.configs === "object" ? doc.configs : {};
145
+ const global = configs.global && typeof configs.global === "object" ? configs.global : {};
146
+ const paths = global.paths && typeof global.paths === "object" ? global.paths : {};
147
+ const special = paths.special;
148
+ const root = requireString(paths.root, "configs.global.paths.root");
149
+ const rootNorm = normalizeRootFolder(root, defaults_default.packageRootFolder).replace(/^\.\//, "");
150
+ const tmpName = typeof paths.tmp === "string" && paths.tmp.trim() ? paths.tmp.trim().replace(/^\.\//, "") : "tmp.yml";
151
+ const sourceRaw = requireString(paths.source, "configs.global.paths.source");
152
+ return {
153
+ rootFolder: rootNorm,
154
+ sourceFolder: normalizeSourceFolder(sourceRaw, sourceRaw),
155
+ framework: requireString(global.framework, "configs.global.framework"),
156
+ layout: readLayoutFromSpecial(special),
157
+ tmpRelPath: `${rootNorm}/${tmpName}`.replace(/\/+/g, "/")
158
+ };
159
+ }
160
+ var seedFromTmp = loadSeedFromBundledTmp();
161
+
162
+ // source/utils/helpers/tmp/tmp-interpolate.ts
163
+ import Handlebars from "handlebars";
164
+
165
+ // source/utils/helpers/tmp/tmp-schema.ts
166
+ function normalizeGlobalType(value) {
167
+ if (value === undefined || value === null || value === "")
168
+ return;
169
+ const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
170
+ if (raw === "workspace" /* WORKSPACE */)
171
+ return "workspace" /* WORKSPACE */;
172
+ if (raw === "api-service" /* API_SERVICE */)
173
+ return "api-service" /* API_SERVICE */;
174
+ if (raw === "frontend" /* FRONTEND */)
175
+ return "frontend" /* FRONTEND */;
176
+ throw new Error(`${defaults_default.packageName}: configs.global.type must be one of ${Object.values(GlobalTypeEnum).join("|")} (got "${String(value)}")`);
177
+ }
17
178
 
18
179
  // source/utils/helpers/workspace/index.ts
19
180
  var TMP_FILE = "tmp.yml";
@@ -31,7 +192,7 @@ function parseScalar(raw) {
31
192
  return trimmed;
32
193
  }
33
194
  function readTmpFile(filePath) {
34
- const text = fs.readFileSync(filePath, "utf8");
195
+ const text = fs2.readFileSync(filePath, "utf8");
35
196
  const out = { path: filePath, folderStructure: { ...DEFAULT_FOLDER_STRUCTURE } };
36
197
  const projectMatch = text.match(/^project:\s*\n(?:[ \t]+[^\n]+\n)*?[ \t]+name:\s*(.+?)\s*(?:#.*)?$/m) ?? text.match(/^project:\s*\n[ \t]+name:\s*(.+?)\s*(?:#.*)?$/m);
37
198
  if (projectMatch)
@@ -48,10 +209,7 @@ function readTmpFile(filePath) {
48
209
  const tmpBlock = text.match(/paths:\s*\n(?:[ \t]+[^\n]+\n)*?[ \t]+tmp:\s*(.+?)\s*(?:#.*)?$/m);
49
210
  if (tmpBlock)
50
211
  out.pathsTmp = parseScalar(tmpBlock[1]);
51
- const clusterBlock = text.match(/cluster:\s*\n(?:[ \t]+[^\n]+\n)*?[ \t]+deployment:\s*(.+?)\s*(?:#.*)?$/m);
52
- if (clusterBlock)
53
- out.clusterDeployment = parseScalar(clusterBlock[1]);
54
- else if (out.projectName)
212
+ if (out.projectName)
55
213
  out.clusterDeployment = out.projectName;
56
214
  out.folderStructure = parseFolderStructure(text);
57
215
  return out;
@@ -70,16 +228,6 @@ function parseFolderStructure(text) {
70
228
  web: readSlot("web")
71
229
  };
72
230
  }
73
- function normalizeGlobalType(value) {
74
- const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
75
- if (raw === "workspace" /* WORKSPACE */)
76
- return "workspace" /* WORKSPACE */;
77
- if (raw === "api-service" /* API_SERVICE */)
78
- return "api-service" /* API_SERVICE */;
79
- if (raw === "frontend" /* FRONTEND */)
80
- return "frontend" /* FRONTEND */;
81
- throw new Error(`@xrystal/core: configs.global.type must be one of ${Object.values(GlobalTypeEnum).join("|")} (got "${String(value)}")`);
82
- }
83
231
  function entryName(meta) {
84
232
  const project = (meta.projectName ?? "").trim();
85
233
  return project || null;
@@ -88,7 +236,7 @@ function entryType(meta, slot) {
88
236
  const explicit = (meta.globalType ?? "").trim();
89
237
  if (explicit) {
90
238
  try {
91
- return normalizeGlobalType(explicit);
239
+ return normalizeGlobalType(explicit) ?? null;
92
240
  } catch {
93
241
  return null;
94
242
  }
@@ -98,15 +246,15 @@ function entryType(meta, slot) {
98
246
  return null;
99
247
  }
100
248
  function findWorkspaceRoot(startDir = process.cwd()) {
101
- let cur = path.resolve(startDir);
249
+ let cur = path2.resolve(startDir);
102
250
  for (;; ) {
103
- const candidate = path.join(cur, TMP_FILE);
104
- if (fs.existsSync(candidate)) {
251
+ const candidate = path2.join(cur, TMP_FILE);
252
+ if (fs2.existsSync(candidate)) {
105
253
  const meta = readTmpFile(candidate);
106
254
  if (meta.globalType === "workspace" /* WORKSPACE */)
107
255
  return cur;
108
256
  }
109
- const parent = path.dirname(cur);
257
+ const parent = path2.dirname(cur);
110
258
  if (parent === cur)
111
259
  break;
112
260
  cur = parent;
@@ -118,7 +266,7 @@ function isTraversableDir(entry, fullPath) {
118
266
  return true;
119
267
  if (entry.isSymbolicLink()) {
120
268
  try {
121
- return fs.statSync(fullPath).isDirectory();
269
+ return fs2.statSync(fullPath).isDirectory();
122
270
  } catch {
123
271
  return false;
124
272
  }
@@ -127,19 +275,19 @@ function isTraversableDir(entry, fullPath) {
127
275
  }
128
276
  function walkTmpUnder(rootDir) {
129
277
  const found = [];
130
- if (!fs.existsSync(rootDir))
278
+ if (!fs2.existsSync(rootDir))
131
279
  return found;
132
280
  const stack = [rootDir];
133
281
  while (stack.length) {
134
282
  const dir = stack.pop();
135
283
  let entries;
136
284
  try {
137
- entries = fs.readdirSync(dir, { withFileTypes: true });
285
+ entries = fs2.readdirSync(dir, { withFileTypes: true });
138
286
  } catch {
139
287
  continue;
140
288
  }
141
289
  for (const entry of entries) {
142
- const full = path.join(dir, entry.name);
290
+ const full = path2.join(dir, entry.name);
143
291
  if (isTraversableDir(entry, full)) {
144
292
  if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
145
293
  continue;
@@ -166,15 +314,15 @@ function repoRootFromTmp(tmpPath, meta) {
166
314
  throw new Error(`tmp path mismatch: expected */${rel}, got ${abs}`);
167
315
  }
168
316
  function findEntries(workspaceRoot) {
169
- const wsMeta = readTmpFile(path.join(workspaceRoot, TMP_FILE));
317
+ const wsMeta = readTmpFile(path2.join(workspaceRoot, TMP_FILE));
170
318
  const fsMap = wsMeta.folderStructure;
171
319
  const entries = [];
172
320
  const seen = new Set;
173
321
  const slots = ["api", "admin", "web"];
174
322
  for (const slot of slots) {
175
- const folder = path.join(workspaceRoot, fsMap[slot]);
323
+ const folder = path2.join(workspaceRoot, fsMap[slot]);
176
324
  for (const tmpPath of walkTmpUnder(folder)) {
177
- if (path.resolve(tmpPath) === path.join(workspaceRoot, TMP_FILE))
325
+ if (path2.resolve(tmpPath) === path2.join(workspaceRoot, TMP_FILE))
178
326
  continue;
179
327
  const meta = readTmpFile(tmpPath);
180
328
  const kind = entryType(meta, slot);
@@ -207,14 +355,14 @@ function findEntries(workspaceRoot) {
207
355
  // source/utils/helpers/xrystal-home/registry.ts
208
356
  var XRYSTAL_HOME_DIR = ".xrystal";
209
357
  function resolveXrystalHome() {
210
- return path2.join(os.homedir(), XRYSTAL_HOME_DIR);
358
+ return path3.join(os.homedir(), XRYSTAL_HOME_DIR);
211
359
  }
212
360
  function registryFilePath() {
213
- return path2.join(resolveXrystalHome(), "registry.json");
361
+ return path3.join(resolveXrystalHome(), "registry.json");
214
362
  }
215
363
  function ensureXrystalHome() {
216
364
  const home = resolveXrystalHome();
217
- fs2.mkdirSync(path2.join(home, "workspaces"), { recursive: true });
365
+ fs3.mkdirSync(path3.join(home, "workspaces"), { recursive: true });
218
366
  return home;
219
367
  }
220
368
  function entryToRegistryProject(entry) {
@@ -227,9 +375,9 @@ function entryToRegistryProject(entry) {
227
375
  };
228
376
  }
229
377
  function normalizeRegistryPath(input) {
230
- const resolved = path2.resolve(input);
378
+ const resolved = path3.resolve(input);
231
379
  try {
232
- return fs2.realpathSync.native(resolved);
380
+ return fs3.realpathSync.native(resolved);
233
381
  } catch {
234
382
  return resolved;
235
383
  }
@@ -237,7 +385,7 @@ function normalizeRegistryPath(input) {
237
385
  function scanWorkspace(workspacePath, workspaceName) {
238
386
  const root = normalizeRegistryPath(workspacePath);
239
387
  const entries = findEntries(root);
240
- const name = workspaceName ?? path2.basename(root);
388
+ const name = workspaceName ?? path3.basename(root);
241
389
  return {
242
390
  name,
243
391
  path: root,
@@ -248,23 +396,23 @@ function scanWorkspace(workspacePath, workspaceName) {
248
396
  function readRegistry() {
249
397
  ensureXrystalHome();
250
398
  const file = registryFilePath();
251
- if (!fs2.existsSync(file)) {
399
+ if (!fs3.existsSync(file)) {
252
400
  return { version: 1, updatedAt: new Date().toISOString(), workspaces: [] };
253
401
  }
254
- return JSON.parse(fs2.readFileSync(file, "utf8"));
402
+ return JSON.parse(fs3.readFileSync(file, "utf8"));
255
403
  }
256
404
  function writeRegistry(registry) {
257
405
  ensureXrystalHome();
258
406
  registry.updatedAt = new Date().toISOString();
259
- fs2.writeFileSync(registryFilePath(), `${JSON.stringify(registry, null, 2)}
407
+ fs3.writeFileSync(registryFilePath(), `${JSON.stringify(registry, null, 2)}
260
408
  `);
261
409
  for (const ws of registry.workspaces) {
262
- const wsDir = path2.join(resolveXrystalHome(), "workspaces", ws.name);
263
- fs2.mkdirSync(wsDir, { recursive: true });
264
- fs2.writeFileSync(path2.join(wsDir, "workspace.json"), `${JSON.stringify(ws, null, 2)}
410
+ const wsDir = path3.join(resolveXrystalHome(), "workspaces", ws.name);
411
+ fs3.mkdirSync(wsDir, { recursive: true });
412
+ fs3.writeFileSync(path3.join(wsDir, "workspace.json"), `${JSON.stringify(ws, null, 2)}
265
413
  `);
266
414
  for (const project of ws.projects) {
267
- fs2.writeFileSync(path2.join(wsDir, `${project.name}.json`), `${JSON.stringify(project, null, 2)}
415
+ fs3.writeFileSync(path3.join(wsDir, `${project.name}.json`), `${JSON.stringify(project, null, 2)}
268
416
  `);
269
417
  }
270
418
  }
@@ -7,11 +7,13 @@ import { brandTitle } from './banner.mjs'
7
7
  import { packageDefaults } from './package-defaults.mjs'
8
8
 
9
9
  const QUICK_COMMANDS = [
10
- { cmd: 'create', hint: '<name> [path]', desc: 'Scaffold service · path defaults to cwd' },
11
- { cmd: 'dev', desc: 'Watch TypeScript entry + dev env' },
12
- { cmd: 'build', desc: 'Bundle to dist/ (tmp.yml layout)' },
13
- { cmd: 'start', desc: 'Run production dist/index.js' },
14
- { cmd: 'test', desc: 'Run tests folder from tmp.yml' },
10
+ { cmd: 'project', desc: 'Where am I? workspace root · linked service · standalone' },
11
+ { cmd: 'sync', desc: 'This project: tsconfig + @xrystal/core pin' },
12
+ { cmd: 'sync --all', desc: 'Inside workspace: every linked api/admin/web project' },
13
+ { cmd: 'tmp', desc: 'Ensure tmp.yml for current scope (inner x/ or outer ./)' },
14
+ { cmd: 'create <name> --workspace', desc: 'Outer tmp + api/general + admin/web slots' },
15
+ { cmd: 'workspaces', desc: 'Global registry ~/.xrystal (not repo tmp.yml)' },
16
+ { cmd: 'dev / build / doctor', desc: 'Develop & diagnostics' },
15
17
  ]
16
18
 
17
19
  const COMMAND_GROUPS = [
@@ -24,22 +26,30 @@ const COMMAND_GROUPS = [
24
26
  { cmd: 'test', desc: 'Run project tests (paths.tests)' },
25
27
  ],
26
28
  },
29
+ {
30
+ title: 'Context',
31
+ items: [
32
+ { cmd: 'project', desc: 'Current folder: workspace root, linked service, standalone, or core library' },
33
+ { cmd: 'workspaces [list|sync]', desc: 'Global registry ~/.xrystal (external to repo tmp files)' },
34
+ ],
35
+ },
27
36
  {
28
37
  title: 'Workspace',
29
38
  items: [
30
- { cmd: 'create <name> --workspace', desc: 'Scaffold workspace + api/general monolith (gpt template)' },
31
- { cmd: 'sync', desc: 'Sync linked projects, end.version, @xrystal/core pin + ~/.xrystal' },
32
- { cmd: 'telepresence dev <deploy>', aliases: 'tp dev', desc: 'Intercept cluster pod → local dev (general, gateway, …)' },
39
+ { cmd: 'create <name> --workspace', desc: 'Outer ./tmp.yml + api/general inner monolith + admin/web' },
40
+ { cmd: 'sync --all', desc: 'From root or any link: all api/admin/web + ~/.xrystal registry' },
41
+ { cmd: 'workspaces [list|sync]', desc: 'Inspect/rescan global registry (separate from xry sync)' },
42
+ { cmd: 'telepresence dev <deploy>', aliases: 'tp dev', desc: 'Intercept cluster pod → local dev' },
33
43
  { cmd: 'telepresence connect', aliases: 'tp connect', desc: 'Connect Telepresence to dev/test namespace' },
34
- { cmd: 'workspaces [list|sync]', desc: 'List registered workspaces and linked projects' },
35
- { cmd: 'workspaces sync', aliases: 'projects sync', desc: 'Rescan cwd workspace into ~/.xrystal' },
36
44
  ],
37
45
  },
38
46
  {
39
47
  title: 'Project',
40
48
  items: [
41
- { cmd: 'create', hint: '<name> [path]', desc: 'Scaffold single service template · optional parent dir' },
42
- { cmd: 'tmp', desc: 'Ensure tmp.yml exists (runtime config seed)' },
49
+ { cmd: 'create', hint: '<name> [path]', desc: 'Standalone service (gpt template + inner x/tmp.yml)' },
50
+ { cmd: 'sync', desc: 'Current project only: tsconfig + @xrystal/core pin + tmp schema' },
51
+ { cmd: 'sync --self', desc: 'Inside workspace: explicit current linked project only' },
52
+ { cmd: 'tmp', desc: 'Ensure tmp.yml for current folder scope · end.version = schema' },
43
53
  { cmd: 'hooks install', desc: 'Install .git/hooks pre-commit version check' },
44
54
  { cmd: 'hooks status', desc: 'Show whether pre-commit hook is installed' },
45
55
  ],
@@ -60,6 +70,7 @@ const COMMAND_GROUPS = [
60
70
  ]
61
71
 
62
72
  const SECTION_COLORS = {
73
+ Context: chalk.bold.white,
63
74
  Develop: chalk.bold.cyan,
64
75
  Workspace: chalk.bold.blue,
65
76
  Project: chalk.bold.green,
@@ -85,6 +96,24 @@ function formatTreeLines(items) {
85
96
  return lines.join('\n')
86
97
  }
87
98
 
99
+ export function formatSyncHelp({ cliName = CLI_PRIMARY_NAME } = {}) {
100
+ const rows = [
101
+ { ctx: 'Standalone service', cmd: `${cliName} sync`, effect: 'tsconfig + pin @xrystal/core + tmp schema' },
102
+ { ctx: 'Workspace root', cmd: `${cliName} sync`, effect: 'all linked projects + registry (same as --all)' },
103
+ { ctx: 'Inside api/admin/web', cmd: `${cliName} sync`, effect: 'current project only (default)' },
104
+ { ctx: 'Inside api/admin/web', cmd: `${cliName} sync --all`, effect: 'every linked project + registry' },
105
+ { ctx: 'Global registry only', cmd: `${cliName} workspaces sync`, effect: 'rescan ~/.xrystal from cwd' },
106
+ ]
107
+ const lines = rows.map((row) => ` ${chalk.gray(row.ctx.padEnd(22))} ${chalk.cyan(row.cmd)}\n${' '.repeat(26)}${chalk.gray(row.effect)}`)
108
+ return [
109
+ chalk.bold.white('\n Sync scope'),
110
+ ...lines,
111
+ '',
112
+ chalk.gray(' xry project — shows which row applies to your cwd'),
113
+ '',
114
+ ].join('\n')
115
+ }
116
+
88
117
  /** Bare CLI — banner altında kısa, işe yarayan komutlar. */
89
118
  export function printQuickStartGuide({ cliName = CLI_PRIMARY_NAME } = {}) {
90
119
  console.log(chalk.bold.yellow('\n Quick start'))
@@ -92,6 +121,7 @@ export function printQuickStartGuide({ cliName = CLI_PRIMARY_NAME } = {}) {
92
121
  console.log('')
93
122
  console.log(` ${chalk.dim('tip')} ${chalk.bold.white(`${cliName} -h`)} ${chalk.gray('· all commands & options')}`)
94
123
  console.log(` ${chalk.dim('tip')} ${chalk.bold.white(`${cliName} doctor`)} ${chalk.gray('· verify install & versions')}`)
124
+ console.log(` ${chalk.dim('tip')} ${chalk.bold.white(`${cliName} tp dev general`)} ${chalk.gray('· telepresence local intercept')}`)
95
125
  console.log('')
96
126
  }
97
127
 
@@ -132,7 +162,7 @@ export function formatRootHelp({ cliName = CLI_PRIMARY_NAME } = {}) {
132
162
 
133
163
  export function formatCreateHelp({ cliName = CLI_PRIMARY_NAME } = {}) {
134
164
  const examples = [
135
- { cmd: `${cliName} create demo --workspace`, desc: '→ workspace with api/admin/web' },
165
+ { cmd: `${cliName} create demo --workspace`, desc: '→ workspace + api/general + admin/web' },
136
166
  { cmd: `${cliName} create my-api`, desc: '→ ./my-api (current folder)' },
137
167
  { cmd: `${cliName} create my-api ..`, desc: '→ ../my-api' },
138
168
  { cmd: `${cliName} create my-api ~/services`, desc: '→ ~/services/my-api' },
@@ -0,0 +1,147 @@
1
+ import fs from 'node:fs'
2
+ import path from 'node:path'
3
+ import yaml from 'yaml'
4
+
5
+ import { packageDefaults } from './package-defaults.mjs'
6
+ import { isCorePackageRoot } from './tmp-layout.mjs'
7
+ import { findEntries, findWorkspaceRoot, workspaceProjectName } from './workspace-resolve.mjs'
8
+ import { getInstalledCoreVersion, readCliPackageJson, readProjectPackageJson, resolveProjectRoot } from './project-root.mjs'
9
+ import { readTmpSchemaVersion, TMP_SCHEMA_VERSION } from './tmp-schema-version.mjs'
10
+
11
+ const WORKSPACE_TYPE = 'workspace'
12
+
13
+ function readTmpMeta(tmpFilePath) {
14
+ if (!tmpFilePath || !fs.existsSync(tmpFilePath)) return null
15
+ try {
16
+ const doc = yaml.parse(fs.readFileSync(tmpFilePath, 'utf8'))
17
+ const globalType = doc?.configs?.global?.type ?? null
18
+ const projectName = doc?.project?.name ?? null
19
+ return {
20
+ path: tmpFilePath,
21
+ projectName,
22
+ globalType,
23
+ schemaVersion: readTmpSchemaVersion(tmpFilePath),
24
+ }
25
+ } catch {
26
+ return { path: tmpFilePath, projectName: null, globalType: null, schemaVersion: null }
27
+ }
28
+ }
29
+
30
+ function findOuterWorkspaceTmp(startDir) {
31
+ const wsRoot = findWorkspaceRoot(startDir)
32
+ if (!wsRoot) return null
33
+ const outer = path.join(wsRoot, 'tmp.yml')
34
+ return fs.existsSync(outer) ? outer : null
35
+ }
36
+
37
+ export function resolveProjectContext(startDir = process.cwd()) {
38
+ const cwd = path.resolve(startDir)
39
+ const cliVersion = readCliPackageJson().version
40
+ const workspaceRoot = findWorkspaceRoot(cwd)
41
+ const projectRoot = resolveProjectRoot(cwd)
42
+ const atWorkspaceRoot = workspaceRoot != null && path.resolve(workspaceRoot) === cwd
43
+
44
+ if (isCorePackageRoot(projectRoot)) {
45
+ const coreRoot = projectRoot
46
+ const innerTmpPath = path.join(coreRoot, packageDefaults.packageRootFolder, `${packageDefaults.tmpBaseName}${packageDefaults.tmpExtension}`)
47
+ const innerMeta = readTmpMeta(fs.existsSync(innerTmpPath) ? innerTmpPath : null)
48
+ return {
49
+ kind: 'core-library',
50
+ label: '@xrystal/core (library source)',
51
+ cwd,
52
+ projectRoot: coreRoot,
53
+ workspaceRoot: null,
54
+ outerTmp: null,
55
+ innerTmp: innerMeta,
56
+ tmp: innerMeta,
57
+ package: readProjectPackageJson(coreRoot),
58
+ core: { cli: cliVersion, declared: cliVersion, installed: cliVersion, isGlobalLibrary: true },
59
+ workspaceEntries: [],
60
+ hints: [
61
+ 'Global runtime library — publish via xry tag',
62
+ 'Consumers: bun add @xrystal/core && xry tmp in their repo',
63
+ ],
64
+ }
65
+ }
66
+
67
+ const outerTmpPath = findOuterWorkspaceTmp(cwd)
68
+ const outerMeta = outerTmpPath ? readTmpMeta(outerTmpPath) : null
69
+
70
+ const innerTmpPath = (() => {
71
+ if (atWorkspaceRoot) return null
72
+ const fromProject = path.join(projectRoot, packageDefaults.packageRootFolder, `${packageDefaults.tmpBaseName}${packageDefaults.tmpExtension}`)
73
+ if (fs.existsSync(fromProject)) return fromProject
74
+ const atRoot = path.join(projectRoot, `${packageDefaults.tmpBaseName}${packageDefaults.tmpExtension}`)
75
+ if (fs.existsSync(atRoot)) return atRoot
76
+ return null
77
+ })()
78
+
79
+ let pkg = null
80
+ const pkgPath = path.join(projectRoot, 'package.json')
81
+ if (fs.existsSync(pkgPath)) {
82
+ try {
83
+ pkg = readProjectPackageJson(projectRoot)
84
+ } catch {
85
+ pkg = null
86
+ }
87
+ }
88
+
89
+ let core = { declared: null, installed: null, path: null, isWorkspace: false }
90
+ if (pkg) {
91
+ core = getInstalledCoreVersion(projectRoot)
92
+ }
93
+ const innerMeta = innerTmpPath ? readTmpMeta(innerTmpPath) : null
94
+
95
+ let kind = 'standalone-service'
96
+ let label = 'Standalone service'
97
+ if (atWorkspaceRoot && outerMeta?.globalType === WORKSPACE_TYPE) {
98
+ kind = 'workspace-root'
99
+ label = 'Workspace root (outer tmp.yml)'
100
+ } else if (workspaceRoot && outerMeta?.globalType === WORKSPACE_TYPE) {
101
+ kind = 'workspace-service'
102
+ label = 'Workspace linked service (inner x/tmp.yml)'
103
+ }
104
+
105
+ const workspaceEntries = workspaceRoot ? findEntries(workspaceRoot) : []
106
+ const selfEntry = workspaceEntries.find((e) => path.resolve(e.path) === path.resolve(projectRoot))
107
+
108
+ const hints = []
109
+ if (kind === 'workspace-root') {
110
+ hints.push('Outer tmp: ./tmp.yml · inner tmp: each api|admin|web project')
111
+ hints.push('xry sync — all linked projects + ~/.xrystal registry')
112
+ hints.push('xry sync --all — same from any folder under this workspace')
113
+ hints.push('xry workspaces — global registry (~/.xrystal), not repo tmp files')
114
+ } else if (kind === 'workspace-service') {
115
+ hints.push(`Outer workspace: ${workspaceRoot}`)
116
+ hints.push('xry sync — this service only (tsconfig + @xrystal/core pin)')
117
+ hints.push('xry sync --all — every linked api/admin/web project + registry')
118
+ hints.push('xry tmp — inner x/tmp.yml · configs.global.type drives loader profile')
119
+ } else {
120
+ hints.push('xry sync — tsconfig + @xrystal/core pin for this repo')
121
+ hints.push('xry tmp — seed inner x/tmp.yml (api-service | frontend | …)')
122
+ hints.push('configs.global.type: frontend skips mongo/redis/kafka unless enabled in tmp')
123
+ }
124
+
125
+ return {
126
+ kind,
127
+ label,
128
+ cwd,
129
+ projectRoot,
130
+ workspaceRoot,
131
+ atWorkspaceRoot,
132
+ outerTmp: outerMeta,
133
+ innerTmp: innerMeta,
134
+ tmp: innerMeta ?? outerMeta,
135
+ selfEntry: selfEntry ?? null,
136
+ package: pkg,
137
+ core: {
138
+ cli: cliVersion,
139
+ declared: core.declared,
140
+ installed: core.installed,
141
+ isGlobalLibrary: false,
142
+ },
143
+ workspaceEntries,
144
+ schemaVersionExpected: TMP_SCHEMA_VERSION,
145
+ hints,
146
+ }
147
+ }
@@ -5,7 +5,7 @@ import yaml from 'yaml'
5
5
 
6
6
  import { Constants } from '../constants/index.mjs'
7
7
  import { ensureTmpFile } from './tmp-layout.mjs'
8
- import { patchTmpEndVersion } from './tmp-end-version.mjs'
8
+ import { ensureTmpSchemaVersion } from './tmp-schema-version.mjs'
9
9
  import { setupProjectGitHooks } from '../scripts/install-git-hooks.mjs'
10
10
 
11
11
  function patchTmpProjectName(tmpFilePath, projectName) {
@@ -19,7 +19,6 @@ export function scaffoldServiceFromTemplate(targetPath, {
19
19
  templateRepoUri = Constants.templateRepoUri,
20
20
  installCommand,
21
21
  cliName,
22
- coreVersion,
23
22
  setupHooks = true,
24
23
  } = {}) {
25
24
  const resolved = path.resolve(targetPath)
@@ -44,7 +43,7 @@ export function scaffoldServiceFromTemplate(targetPath, {
44
43
 
45
44
  const tmpResult = ensureTmpFile(resolved)
46
45
  patchTmpProjectName(tmpResult.tmpFilePath, projectName)
47
- patchTmpEndVersion(tmpResult.tmpFilePath, coreVersion)
46
+ ensureTmpSchemaVersion(tmpResult.tmpFilePath)
48
47
 
49
48
  execSync(installCommand, { cwd: resolved, stdio: 'inherit' })
50
49