@netgreener/runtime 0.1.8 → 0.1.10

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 (114) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/TUTORIAL.md +120 -29
  3. package/dist/aggregator.d.ts +12 -2
  4. package/dist/aggregator.js +135 -8
  5. package/dist/analyze/buildResourceFindings.d.ts +4 -0
  6. package/dist/analyze/buildResourceFindings.js +17 -0
  7. package/dist/analyze/cli.d.ts +1 -0
  8. package/dist/analyze/cli.js +22 -1
  9. package/dist/analyze/declaredExternalApis.d.ts +31 -0
  10. package/dist/analyze/declaredExternalApis.js +174 -0
  11. package/dist/analyze/index.d.ts +1 -0
  12. package/dist/analyze/index.js +1 -0
  13. package/dist/auto.d.ts +7 -0
  14. package/dist/auto.js +8 -0
  15. package/dist/bullmq.d.ts +2 -2
  16. package/dist/bullmq.js +28 -58
  17. package/dist/carbonLedger.d.ts +28 -0
  18. package/dist/carbonLedger.js +52 -0
  19. package/dist/cgroupV2.d.ts +44 -0
  20. package/dist/cgroupV2.js +174 -0
  21. package/dist/cli/helpText.d.ts +3 -3
  22. package/dist/cli/helpText.js +42 -35
  23. package/dist/cli/netgreener.d.ts +7 -7
  24. package/dist/cli/netgreener.js +23 -16
  25. package/dist/cli/runCli.d.ts +20 -0
  26. package/dist/cli/runCli.js +249 -0
  27. package/dist/cli/runPreload.d.ts +5 -0
  28. package/dist/cli/runPreload.js +43 -0
  29. package/dist/collectorMetadata.d.ts +1 -1
  30. package/dist/collectorMetadata.js +2 -0
  31. package/dist/config.d.ts +2 -0
  32. package/dist/config.js +6 -2
  33. package/dist/exporter.d.ts +7 -2
  34. package/dist/exporter.js +12 -6
  35. package/dist/express.js +17 -6
  36. package/dist/externalApiMeter.d.ts +51 -2
  37. package/dist/externalApiMeter.js +379 -26
  38. package/dist/fastify.js +17 -6
  39. package/dist/index.d.ts +12 -2
  40. package/dist/index.js +11 -1
  41. package/dist/init.d.ts +30 -0
  42. package/dist/init.js +31 -0
  43. package/dist/lifecycle.d.ts +45 -0
  44. package/dist/lifecycle.js +112 -0
  45. package/dist/managedCollectorLauncher.d.ts +37 -0
  46. package/dist/managedCollectorLauncher.js +162 -0
  47. package/dist/mcpToolMeter.d.ts +101 -0
  48. package/dist/mcpToolMeter.js +496 -0
  49. package/dist/n4/deploymentMatrix.d.ts +9 -5
  50. package/dist/n4/deploymentMatrix.js +13 -9
  51. package/dist/n4/missingnessInventory.js +3 -3
  52. package/dist/next.d.ts +89 -0
  53. package/dist/next.js +328 -0
  54. package/dist/nextConfig.d.ts +34 -0
  55. package/dist/nextConfig.js +73 -0
  56. package/dist/nextEntryTransform.d.ts +9 -0
  57. package/dist/nextEntryTransform.js +181 -0
  58. package/dist/occupancyTracker.d.ts +27 -0
  59. package/dist/occupancyTracker.js +87 -0
  60. package/dist/optimize/apply.d.ts +38 -0
  61. package/dist/optimize/apply.js +173 -0
  62. package/dist/optimize/cli.d.ts +26 -0
  63. package/dist/optimize/cli.js +323 -0
  64. package/dist/optimize/index.d.ts +6 -0
  65. package/dist/optimize/index.js +5 -0
  66. package/dist/optimize/llmApply.d.ts +22 -0
  67. package/dist/optimize/llmApply.js +80 -0
  68. package/dist/optimize/llmSession.d.ts +88 -0
  69. package/dist/optimize/llmSession.js +135 -0
  70. package/dist/optimize/provider.d.ts +17 -0
  71. package/dist/optimize/provider.js +119 -0
  72. package/dist/optimize/safePatches.d.ts +18 -0
  73. package/dist/optimize/safePatches.js +247 -0
  74. package/dist/optimize/types.d.ts +79 -0
  75. package/dist/optimize/types.js +6 -0
  76. package/dist/optimize/verification.d.ts +16 -0
  77. package/dist/optimize/verification.js +165 -0
  78. package/dist/processResources.d.ts +5 -0
  79. package/dist/processResources.js +28 -4
  80. package/dist/processRuntime.js +7 -28
  81. package/dist/processTree.d.ts +47 -0
  82. package/dist/processTree.js +148 -0
  83. package/dist/runContextEnrichment.d.ts +11 -0
  84. package/dist/runContextEnrichment.js +92 -0
  85. package/dist/runtime.d.ts +36 -1
  86. package/dist/runtime.js +140 -17
  87. package/dist/sdk/client.d.ts +152 -0
  88. package/dist/sdk/client.js +396 -0
  89. package/dist/sdk/gitUrl.d.ts +6 -0
  90. package/dist/sdk/gitUrl.js +87 -0
  91. package/dist/sdk/index.d.ts +5 -0
  92. package/dist/sdk/index.js +5 -0
  93. package/dist/serverlessHints.d.ts +9 -6
  94. package/dist/serverlessHints.js +10 -7
  95. package/dist/taskMeter.d.ts +14 -0
  96. package/dist/taskMeter.js +53 -0
  97. package/dist/types.d.ts +43 -0
  98. package/examples/aca-container-gate/Dockerfile +20 -0
  99. package/examples/aca-container-gate/azure-container-app.yaml +27 -0
  100. package/examples/aca-container-gate/gate.env +7 -0
  101. package/examples/aca-container-gate/server.mjs +117 -0
  102. package/examples/azure-functions-gate/.funcignore +6 -0
  103. package/examples/azure-functions-gate/README.md +25 -0
  104. package/examples/azure-functions-gate/host.json +15 -0
  105. package/examples/azure-functions-gate/package-lock.json +161 -0
  106. package/examples/azure-functions-gate/package.json +14 -0
  107. package/examples/azure-functions-gate/src/functions/health.js +27 -0
  108. package/examples/express-local-live-smoke.mjs +127 -0
  109. package/examples/extractRunId.mjs +11 -0
  110. package/examples/next-pilot-dry-run.mjs +32 -0
  111. package/examples/serverless-thin-gate.mjs +89 -0
  112. package/fixtures/run-smoke/hello.mjs +4 -0
  113. package/loaders/next-entry-loader.cjs +14 -0
  114. package/package.json +25 -2
@@ -1,21 +1,23 @@
1
1
  /**
2
- * Shared CLI help / version copy for the Node ``netgreener`` scaffold.
3
- * Upload remains off; run/optimize stay stubs.
2
+ * Shared CLI help / version copy for the Node ``netgreener`` CLI.
4
3
  */
5
- export const CLI_VERSION = '0.1.0';
4
+ export const CLI_VERSION = '0.1.8';
6
5
  export function formatRootHelp() {
7
- return `NetGreener Node CLI ${CLI_VERSION} (scaffold)
6
+ return `NetGreener Node CLI ${CLI_VERSION}
8
7
 
9
8
  Usage:
10
9
  netgreener <command> [options]
11
10
  netgreener help [command]
12
11
 
13
12
  Commands:
14
- analyze <projectDir> Local resource Analyze (manifest + resource_finding_v1)
15
- run (stub) Not implemented — will not upload
16
- optimize (stub) Not implemented — will not upload
17
- help [command] Show this help or a command's help
18
- version Show version
13
+ analyze <projectDir> Local resource Analyze (manifest + findings)
14
+ run <script> [projectDir] Execute script with process metering (+ optional upload)
15
+ optimize <projectDir> Local proposals; --llm for api_server optimize session
16
+ optimize <projectDir> --apply Safe local patches only (VerificationProvider)
17
+ optimize <projectDir> --llm Shared LLM /optimize/function (token + project-id)
18
+ optimize … --llm --apply-verified LLM splice + VerificationProvider (not --apply)
19
+ help [command] Show this help or a command's help
20
+ version Show version
19
21
 
20
22
  Global:
21
23
  -h, --help Show this help
@@ -23,19 +25,21 @@ Global:
23
25
 
24
26
  Examples:
25
27
  netgreener analyze ./my-app
26
- netgreener analyze ./my-app --json-summary
27
- netgreener analyze ./my-app --fail-on any --max-at-or-above 0
28
- netgreener analyze ./my-app --paths src/hot.ts,src/retry.ts --findings-only
29
- netgreener-analyze ./my-app # alias bin (same Analyze path)
28
+ netgreener analyze ./my-app --json-summary --fail-on any
29
+ netgreener run ./jobs/report.mjs . --no-upload
30
+ netgreener optimize ./my-app
31
+ netgreener-analyze ./my-app
30
32
 
31
33
  Notes:
32
- • Analyze prints local candidates only (upload=never).
33
- • optimize / run are stubs (exit 2) — see OPTIMIZE_STUB.md; no upload / no patches.
34
- • Does not modify RunSession / metering pipelines.
35
- • VS Code: Node-first folders use this local Analyze path (same guarantee).
36
-
37
- Analyze options: netgreener help analyze
38
- Optimize stub: netgreener help optimize
34
+ • Analyze is local only (upload=never).
35
+ • run meters via process runtime; default EXPORT_MODE stays direct.
36
+ • optimize emits proposals; --apply only for auto_apply_safe + VerificationProvider.
37
+ • --llm uses shared api_server /optimize/function; --apply-verified for VP-gated writes.
38
+ • Same api_server brain as Python — no Node server fork.
39
+
40
+ Analyze: netgreener help analyze
41
+ Run: netgreener help run
42
+ Optimize: netgreener help optimize
39
43
  `;
40
44
  }
41
45
  export function formatAnalyzeHelp() {
@@ -55,6 +59,7 @@ Options:
55
59
  --json-summary Emit netgreener_analyze_gate_summary_v0 only (CI)
56
60
  --fail-on any|<mechanism>[,…] Fail (exit 1) when matching candidates exceed cap
57
61
  --max-at-or-above <n> With --fail-on: allow up to N matches (default 0)
62
+ --depth quick|standard|thorough Python-parity LLM budget (default standard; static scan ignores)
58
63
  --quiet No stderr status lines
59
64
  -h, --help Show this help
60
65
 
@@ -70,30 +75,32 @@ Examples:
70
75
  CI tip: pair --json-summary with --fail-on for gate annotations without upload.
71
76
  `;
72
77
  }
78
+ /** @deprecated Prefer formatOptimizeHelp / formatRunHelp. Kept for older tests. */
73
79
  export function formatStubHelp(command) {
74
80
  if (command === 'optimize') {
75
- return `netgreener optimize: not implemented yet in the Node CLI scaffold.
81
+ return `netgreener optimize: local OptimizerProvider + optional --llm (see OPTIMIZE_STUB.md).
76
82
 
77
- This is an intentional stub (MP4 / N5), not a silent no-op:
78
- • exit code 2 when invoked as a command
79
- • no upload, no LLM call, no patch apply, no tree writes
80
- • no api_server /optimize/* wiring
83
+ Default (local):
84
+ • --apply only writes auto_apply_safe patches (verify before+after; rollback on fail)
85
+ • no invented savings
86
+ • no upload
81
87
 
82
- Until a real JS/TS OptimizerProvider + VerificationProvider land behind the
83
- shared MP4 interfaces, use local Analyze only:
88
+ Opt-in LLM (owner OK):
89
+ netgreener optimize <projectDir> --llm --project-id N
90
+ • requires NETGREENER_TOKEN
91
+ • POST /optimize/function — prints optimize_llm_session_v0
92
+ • --llm --apply-verified for VerificationProvider-gated LLM writes (not --apply)
84
93
 
85
- netgreener analyze <projectDir>
86
- netgreener analyze <projectDir> --fail-on any --json-summary
87
- netgreener help analyze
94
+ netgreener optimize <projectDir>
95
+ netgreener optimize <projectDir> --apply --skip-test
96
+ netgreener optimize <projectDir> --llm --apply-verified --project-id N
97
+ netgreener analyze <projectDir> --json-summary
88
98
 
89
- Boundary doc: OPTIMIZE_STUB.md (in the @netgreener/runtime package root).
90
99
  `;
91
100
  }
92
- return `netgreener ${command}: not implemented yet in the Node CLI scaffold.
101
+ return `netgreener run: use \`netgreener help run\` for the metered script runner.
93
102
 
94
- No upload is performed. Use local Analyze instead:
103
+ netgreener run <script> [projectDir] [--no-upload]
95
104
 
96
- netgreener analyze <projectDir>
97
- netgreener help analyze
98
105
  `;
99
106
  }
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * NetGreener Node CLI entry (scaffold).
3
+ * NetGreener Node CLI entry.
4
4
  *
5
- * netgreener analyze <dir> — resource Analyze candidates (implemented)
6
- * netgreener run … — stub (not implemented; no upload)
7
- * netgreener optimize … — stub (not implemented; no upload)
5
+ * netgreener analyze <dir> — resource Analyze candidates (local)
6
+ * netgreener run <script> … — execute script with process metering
7
+ * netgreener optimize <dir> — local OptimizerProvider proposals (no apply)
8
8
  *
9
- * Does not change RunSession / metering pipelines. Upload remains off.
9
+ * Does not flip EXPORT_MODE. Optimize never mutates the tree (see OPTIMIZE_STUB.md).
10
10
  */
11
- /** Dispatch top-level ``netgreener`` commands. */
12
- export declare function runNetgreenerCli(argv: string[]): number;
11
+ /** Dispatch top-level ``netgreener`` commands. Sync entry; ``run`` may return a Promise. */
12
+ export declare function runNetgreenerCli(argv: string[]): number | Promise<number>;
@@ -1,21 +1,19 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * NetGreener Node CLI entry (scaffold).
3
+ * NetGreener Node CLI entry.
4
4
  *
5
- * netgreener analyze <dir> — resource Analyze candidates (implemented)
6
- * netgreener run … — stub (not implemented; no upload)
7
- * netgreener optimize … — stub (not implemented; no upload)
5
+ * netgreener analyze <dir> — resource Analyze candidates (local)
6
+ * netgreener run <script> … — execute script with process metering
7
+ * netgreener optimize <dir> — local OptimizerProvider proposals (no apply)
8
8
  *
9
- * Does not change RunSession / metering pipelines. Upload remains off.
9
+ * Does not flip EXPORT_MODE. Optimize never mutates the tree (see OPTIMIZE_STUB.md).
10
10
  */
11
11
  import { resolve } from 'node:path';
12
12
  import { pathToFileURL } from 'node:url';
13
13
  import { runAnalyzeCli } from '../analyze/cli.js';
14
- import { CLI_VERSION, formatAnalyzeHelp, formatRootHelp, formatStubHelp, } from './helpText.js';
15
- function stubCommand(name) {
16
- process.stderr.write(formatStubHelp(name));
17
- return 2;
18
- }
14
+ import { formatOptimizeHelp, runOptimizeCli } from '../optimize/cli.js';
15
+ import { CLI_VERSION, formatAnalyzeHelp, formatRootHelp, } from './helpText.js';
16
+ import { formatRunHelp, runRunCli } from './runCli.js';
19
17
  function printHelpFor(topic) {
20
18
  const key = (topic || '').trim().toLowerCase();
21
19
  if (!key || key === 'help') {
@@ -26,15 +24,19 @@ function printHelpFor(topic) {
26
24
  process.stdout.write(formatAnalyzeHelp());
27
25
  return 0;
28
26
  }
29
- if (key === 'run' || key === 'optimize') {
30
- process.stderr.write(formatStubHelp(key));
27
+ if (key === 'run') {
28
+ process.stdout.write(formatRunHelp());
29
+ return 0;
30
+ }
31
+ if (key === 'optimize') {
32
+ process.stdout.write(formatOptimizeHelp());
31
33
  return 0;
32
34
  }
33
35
  process.stderr.write(`Unknown help topic: ${topic}\n\n`);
34
36
  process.stdout.write(formatRootHelp());
35
37
  return 2;
36
38
  }
37
- /** Dispatch top-level ``netgreener`` commands. */
39
+ /** Dispatch top-level ``netgreener`` commands. Sync entry; ``run`` may return a Promise. */
38
40
  export function runNetgreenerCli(argv) {
39
41
  const [cmd, ...rest] = argv;
40
42
  if (!cmd || cmd === '-h' || cmd === '--help') {
@@ -51,8 +53,11 @@ export function runNetgreenerCli(argv) {
51
53
  if (cmd === 'analyze') {
52
54
  return runAnalyzeCli(rest);
53
55
  }
54
- if (cmd === 'run' || cmd === 'optimize') {
55
- return stubCommand(cmd);
56
+ if (cmd === 'run') {
57
+ return runRunCli(rest);
58
+ }
59
+ if (cmd === 'optimize') {
60
+ return runOptimizeCli(rest);
56
61
  }
57
62
  process.stderr.write(`Unknown command: ${cmd}\n\n`);
58
63
  process.stdout.write(formatRootHelp());
@@ -61,5 +66,7 @@ export function runNetgreenerCli(argv) {
61
66
  const invokedDirectly = typeof process.argv[1] === 'string' &&
62
67
  pathToFileURL(resolve(process.argv[1])).href === import.meta.url;
63
68
  if (invokedDirectly) {
64
- process.exitCode = runNetgreenerCli(process.argv.slice(2));
69
+ Promise.resolve(runNetgreenerCli(process.argv.slice(2))).then((code) => {
70
+ process.exitCode = code;
71
+ });
65
72
  }
@@ -0,0 +1,20 @@
1
+ /**
2
+ * ``netgreener run <script> [projectDir]`` — execute a Node script with process metering.
3
+ *
4
+ * Twin intent of Python ``netgreener run <script> .``: really run the script and
5
+ * measure. Child process loads ``runPreload`` so metering happens inside the
6
+ * workload process. Uploads to existing api_server (default direct).
7
+ */
8
+ export type RunCliFlags = {
9
+ script: string;
10
+ projectDir: string;
11
+ noUpload: boolean;
12
+ dryRun: boolean;
13
+ noAnalyze: boolean;
14
+ help: boolean;
15
+ scriptArgs: string[];
16
+ };
17
+ export declare function formatRunHelp(): string;
18
+ export declare function parseRunArgs(argv: string[]): RunCliFlags;
19
+ /** Run the metered script CLI. Returns process exit code. */
20
+ export declare function runRunCli(argv: string[]): Promise<number>;
@@ -0,0 +1,249 @@
1
+ /**
2
+ * ``netgreener run <script> [projectDir]`` — execute a Node script with process metering.
3
+ *
4
+ * Twin intent of Python ``netgreener run <script> .``: really run the script and
5
+ * measure. Child process loads ``runPreload`` so metering happens inside the
6
+ * workload process. Uploads to existing api_server (default direct).
7
+ */
8
+ import { spawn } from 'node:child_process';
9
+ import { accessSync, constants, statSync } from 'node:fs';
10
+ import { dirname, isAbsolute, join, resolve } from 'node:path';
11
+ import { pathToFileURL, fileURLToPath } from 'node:url';
12
+ import { runAnalyzeCli } from '../analyze/cli.js';
13
+ import { configReady, loadRuntimeConfig } from '../config.js';
14
+ import { childEnvForManagedCollector, normalizedCollectorMode, startManagedCollector, } from '../managedCollectorLauncher.js';
15
+ const preloadHref = pathToFileURL(join(dirname(fileURLToPath(import.meta.url)), 'runPreload.js')).href;
16
+ export function formatRunHelp() {
17
+ return `Usage: netgreener run <script> [projectDir] [--] [scriptArgs...]
18
+
19
+ Really execute a Node script and meter the process window (CPU/RSS via
20
+ node_process_*). Uploads a RunSession to the existing NetGreener api_server
21
+ when credentials are set (same brain as Python — no Node api_server).
22
+
23
+ Arguments:
24
+ script Entry file (.js / .mjs / .cjs)
25
+ projectDir Working directory (default: script's directory)
26
+
27
+ Options:
28
+ --no-upload Do not upload (forces dry-run flush)
29
+ --dry-run Same as --no-upload for metering payload
30
+ --no-analyze Skip local Analyze pass after the script exits
31
+ -h, --help Show this help
32
+
33
+ Env (live upload):
34
+ NETGREENER_SERVICE_RUNTIME=1
35
+ NETGREENER_TOKEN=ngs_…
36
+ NETGREENER_PROJECT_ID=<id>
37
+ NETGREENER_API_URL=… (optional)
38
+ NETGREENER_EXPORT_MODE=direct (default — do not flip without owner OK)
39
+ NETGREENER_COLLECTOR_MODE=managed (opt-in: start sibling collector; child uses EXPORT_MODE=collector)
40
+
41
+ Examples:
42
+ netgreener run ./jobs/report.mjs .
43
+ netgreener run ./jobs/report.mjs ./my-app --no-upload
44
+ netgreener run ./server.mjs . -- --port 3000
45
+
46
+ Notes:
47
+ • Analyze after run is local only (upload=never), same as \`netgreener analyze\`.
48
+ • .ts entrypoints: compile first or use a TS runner; metered .ts wrap comes later.
49
+ • Managed collector needs Python \`netgreener.collector_server\` on PATH; Windows = tcp:// only.
50
+ `;
51
+ }
52
+ export function parseRunArgs(argv) {
53
+ const flags = {
54
+ script: '',
55
+ projectDir: '',
56
+ noUpload: false,
57
+ dryRun: false,
58
+ noAnalyze: false,
59
+ help: false,
60
+ scriptArgs: [],
61
+ };
62
+ const positionals = [];
63
+ let passthrough = false;
64
+ for (let i = 0; i < argv.length; i += 1) {
65
+ const arg = argv[i] ?? '';
66
+ if (passthrough) {
67
+ flags.scriptArgs.push(arg);
68
+ continue;
69
+ }
70
+ if (arg === '--') {
71
+ passthrough = true;
72
+ continue;
73
+ }
74
+ if (arg === '-h' || arg === '--help') {
75
+ flags.help = true;
76
+ continue;
77
+ }
78
+ if (arg === '--no-upload') {
79
+ flags.noUpload = true;
80
+ continue;
81
+ }
82
+ if (arg === '--dry-run') {
83
+ flags.dryRun = true;
84
+ continue;
85
+ }
86
+ if (arg === '--no-analyze') {
87
+ flags.noAnalyze = true;
88
+ continue;
89
+ }
90
+ if (arg.startsWith('-')) {
91
+ throw new Error(`Unknown option: ${arg}`);
92
+ }
93
+ positionals.push(arg);
94
+ }
95
+ flags.script = positionals[0] || '';
96
+ flags.projectDir = positionals[1] || '';
97
+ return flags;
98
+ }
99
+ function assertJsEntrypoint(scriptPath) {
100
+ const lower = scriptPath.toLowerCase();
101
+ if (lower.endsWith('.ts') || lower.endsWith('.tsx') || lower.endsWith('.mts')) {
102
+ throw new Error('TypeScript entrypoints are not metered yet. Compile to .js/.mjs first.');
103
+ }
104
+ }
105
+ function buildChildEnv(flags) {
106
+ const dry = flags.noUpload || flags.dryRun || process.env.NETGREENER_RUNTIME_DRY_RUN === '1';
107
+ const config = loadRuntimeConfig({
108
+ ...process.env,
109
+ NETGREENER_SERVICE_RUNTIME: process.env.NETGREENER_SERVICE_RUNTIME || '1',
110
+ ...(dry
111
+ ? {
112
+ NETGREENER_RUNTIME_DRY_RUN: '1',
113
+ NETGREENER_TOKEN: process.env.NETGREENER_TOKEN || 'ngs_local_dry_run',
114
+ NETGREENER_PROJECT_ID: process.env.NETGREENER_PROJECT_ID || '1',
115
+ }
116
+ : {}),
117
+ });
118
+ const ready = configReady(config);
119
+ if (!ready.ok) {
120
+ throw new Error(`runtime config not ready (${ready.reason}). ` +
121
+ `Set NETGREENER_TOKEN + NETGREENER_PROJECT_ID, or pass --no-upload / --dry-run.`);
122
+ }
123
+ return {
124
+ ...process.env,
125
+ NETGREENER_SERVICE_RUNTIME: '1',
126
+ NETGREENER_TOKEN: config.token,
127
+ NETGREENER_PROJECT_ID: String(config.projectId),
128
+ NETGREENER_API_URL: config.apiUrl,
129
+ ...(config.dryRun ? { NETGREENER_RUNTIME_DRY_RUN: '1' } : {}),
130
+ ...(config.organizationId != null
131
+ ? { NETGREENER_ORG_ID: String(config.organizationId) }
132
+ : {}),
133
+ ...(config.organizationId == null && config.organizationSlug
134
+ ? { NETGREENER_ORG_SLUG: config.organizationSlug }
135
+ : {}),
136
+ };
137
+ }
138
+ function spawnScript(scriptAbs, cwd, scriptArgs, env) {
139
+ return new Promise((resolveExit) => {
140
+ const child = spawn(process.execPath, ['--import', preloadHref, scriptAbs, ...scriptArgs], {
141
+ cwd,
142
+ stdio: 'inherit',
143
+ env,
144
+ windowsHide: true,
145
+ });
146
+ child.on('error', (err) => {
147
+ process.stderr.write(`netgreener run: failed to start script: ${err.message}\n`);
148
+ resolveExit(1);
149
+ });
150
+ child.on('exit', (code, signal) => {
151
+ if (signal) {
152
+ process.stderr.write(`netgreener run: script terminated by ${signal}\n`);
153
+ resolveExit(1);
154
+ return;
155
+ }
156
+ resolveExit(typeof code === 'number' ? code : 1);
157
+ });
158
+ });
159
+ }
160
+ /** Run the metered script CLI. Returns process exit code. */
161
+ export async function runRunCli(argv) {
162
+ let flags;
163
+ try {
164
+ flags = parseRunArgs(argv);
165
+ }
166
+ catch (err) {
167
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n\n`);
168
+ process.stdout.write(formatRunHelp());
169
+ return 2;
170
+ }
171
+ if (flags.help) {
172
+ process.stdout.write(formatRunHelp());
173
+ return 0;
174
+ }
175
+ if (!flags.script) {
176
+ process.stderr.write('netgreener run: missing <script>\n\n');
177
+ process.stdout.write(formatRunHelp());
178
+ return 2;
179
+ }
180
+ const scriptAbs = isAbsolute(flags.script)
181
+ ? flags.script
182
+ : resolve(process.cwd(), flags.script);
183
+ try {
184
+ accessSync(scriptAbs, constants.R_OK);
185
+ if (!statSync(scriptAbs).isFile())
186
+ throw new Error('not a file');
187
+ }
188
+ catch {
189
+ process.stderr.write(`netgreener run: script not found: ${scriptAbs}\n`);
190
+ return 2;
191
+ }
192
+ try {
193
+ assertJsEntrypoint(scriptAbs);
194
+ }
195
+ catch (err) {
196
+ process.stderr.write(`netgreener run: ${err instanceof Error ? err.message : String(err)}\n`);
197
+ return 2;
198
+ }
199
+ const projectAbs = flags.projectDir
200
+ ? isAbsolute(flags.projectDir)
201
+ ? flags.projectDir
202
+ : resolve(process.cwd(), flags.projectDir)
203
+ : resolve(scriptAbs, '..');
204
+ let childEnv;
205
+ try {
206
+ childEnv = buildChildEnv(flags);
207
+ }
208
+ catch (err) {
209
+ process.stderr.write(`netgreener run: ${err instanceof Error ? err.message : String(err)}\n`);
210
+ return 2;
211
+ }
212
+ let managed = null;
213
+ if (normalizedCollectorMode(childEnv) === 'managed') {
214
+ try {
215
+ process.stderr.write('netgreener run: COLLECTOR_MODE=managed — starting sibling collector…\n');
216
+ managed = await startManagedCollector({ env: childEnv });
217
+ if (managed) {
218
+ childEnv = childEnvForManagedCollector(childEnv, managed.endpoint);
219
+ process.stderr.write(`netgreener run: collector ready at ${managed.endpoint}\n`);
220
+ }
221
+ }
222
+ catch (err) {
223
+ process.stderr.write(`netgreener run: managed collector failed: ${err instanceof Error ? err.message : String(err)}\n`);
224
+ return 2;
225
+ }
226
+ }
227
+ const dry = childEnv.NETGREENER_RUNTIME_DRY_RUN === '1';
228
+ const exportMode = (childEnv.NETGREENER_EXPORT_MODE || 'direct').toLowerCase();
229
+ process.stderr.write(`netgreener run: metering ${scriptAbs} (cwd=${projectAbs}` +
230
+ `${dry ? ', dry-run' : ', upload'}, export=${exportMode})…\n`);
231
+ let exitCode = 1;
232
+ try {
233
+ exitCode = await spawnScript(scriptAbs, projectAbs, flags.scriptArgs, childEnv);
234
+ }
235
+ finally {
236
+ if (managed) {
237
+ process.stderr.write('netgreener run: draining managed collector…\n');
238
+ await managed.stop();
239
+ }
240
+ }
241
+ if (!flags.noAnalyze) {
242
+ process.stderr.write('netgreener run: local analyze (upload=never)…\n');
243
+ const analyzeCode = runAnalyzeCli([projectAbs, '--quiet']);
244
+ if (analyzeCode !== 0) {
245
+ process.stderr.write(`netgreener run: analyze exited ${analyzeCode}\n`);
246
+ }
247
+ }
248
+ return exitCode;
249
+ }
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Preload for ``netgreener run`` — meters the child Node process that executes
3
+ * the user script. Loaded via ``node --import <this-module> <script>``.
4
+ */
5
+ export {};
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Preload for ``netgreener run`` — meters the child Node process that executes
3
+ * the user script. Loaded via ``node --import <this-module> <script>``.
4
+ */
5
+ import { loadRuntimeConfig } from '../config.js';
6
+ import { beginProcessResourceSample, endProcessResourceSample, } from '../processResources.js';
7
+ import { startProcessRuntime } from '../processRuntime.js';
8
+ const config = loadRuntimeConfig(process.env);
9
+ const runtime = startProcessRuntime({ config });
10
+ const resourceMark = beginProcessResourceSample();
11
+ const startedMs = performance.now();
12
+ let flushed = false;
13
+ async function shutdownFlush() {
14
+ if (flushed)
15
+ return;
16
+ flushed = true;
17
+ try {
18
+ const resources = endProcessResourceSample(resourceMark);
19
+ if (runtime.enabled) {
20
+ runtime.recordTask({
21
+ serviceUnit: 'task:netgreener_run',
22
+ durationMs: performance.now() - startedMs,
23
+ error: false,
24
+ tenantId: null,
25
+ cpuTimeMs: resources.cpuTimeMs,
26
+ peakRssKb: resources.rssKb,
27
+ });
28
+ }
29
+ await runtime.shutdown();
30
+ }
31
+ catch {
32
+ // best-effort on exit
33
+ }
34
+ }
35
+ process.once('beforeExit', () => {
36
+ void shutdownFlush();
37
+ });
38
+ process.once('SIGINT', () => {
39
+ void shutdownFlush().finally(() => process.exit(130));
40
+ });
41
+ process.once('SIGTERM', () => {
42
+ void shutdownFlush().finally(() => process.exit(143));
43
+ });
@@ -8,7 +8,7 @@
8
8
  * N6 packaging doc twin: ``PACKAGING.md``.
9
9
  */
10
10
  /** Known collector metadata strings emitted by this package. */
11
- export declare const COMPATIBLE_COLLECTOR_METADATA: readonly ["express_middleware", "fastify_middleware", "nest_express_middleware", "nest_fastify_middleware", "node_process", "bullmq_worker", "outbound_http"];
11
+ export declare const COMPATIBLE_COLLECTOR_METADATA: readonly ["express_middleware", "fastify_middleware", "nest_express_middleware", "nest_fastify_middleware", "next_app_router", "node_process", "bullmq_worker", "outbound_http"];
12
12
  export type CompatibleCollectorMetadata = (typeof COMPATIBLE_COLLECTOR_METADATA)[number];
13
13
  export declare function isCompatibleCollectorMetadata(value: string): boolean;
14
14
  /** Short descriptions for packaging / dogfood docs (not user-facing UI copy). */
@@ -13,6 +13,7 @@ export const COMPATIBLE_COLLECTOR_METADATA = [
13
13
  'fastify_middleware',
14
14
  'nest_express_middleware',
15
15
  'nest_fastify_middleware',
16
+ 'next_app_router',
16
17
  'node_process',
17
18
  'bullmq_worker',
18
19
  'outbound_http',
@@ -27,6 +28,7 @@ export const COLLECTOR_METADATA_NOTES = {
27
28
  fastify_middleware: 'Fastify plugin request/response metering origin',
28
29
  nest_express_middleware: 'Nest on Express adapter middleware origin',
29
30
  nest_fastify_middleware: 'Nest on Fastify adapter middleware origin',
31
+ next_app_router: 'Next.js App Router route-handler metering origin (Wave 3 pilot)',
30
32
  node_process: 'Process/cron helper origin (no HTTP framework)',
31
33
  bullmq_worker: 'BullMQ worker job flush origin',
32
34
  outbound_http: 'Outbound fetch/axios/undici external API meter origin',
package/dist/config.d.ts CHANGED
@@ -4,6 +4,8 @@ export type RuntimeConfig = {
4
4
  token: string;
5
5
  projectId: number;
6
6
  organizationId: number | null;
7
+ /** OP2: human slug when NETGREENER_ORG_ID unset; resolve via SDK before needing org headers. */
8
+ organizationSlug?: string | null;
7
9
  flushIntervalMs: number;
8
10
  dryRun: boolean;
9
11
  deployEnvironment: string | null;
package/dist/config.js CHANGED
@@ -44,6 +44,7 @@ export function loadRuntimeConfig(env = process.env) {
44
44
  const token = (env.NETGREENER_TOKEN || '').trim();
45
45
  const projectId = envPositiveSafeInteger(env, 'NETGREENER_PROJECT_ID', 0);
46
46
  const organizationIdRaw = envPositiveSafeInteger(env, 'NETGREENER_ORG_ID', 0);
47
+ const organizationSlug = (env.NETGREENER_ORG_SLUG || '').trim().toLowerCase() || null;
47
48
  const flushMinutes = envNumberInRange(env, 'NETGREENER_RUNTIME_FLUSH_MINUTES', DEFAULT_RUNTIME_FLUSH_MINUTES, MIN_RUNTIME_FLUSH_MINUTES, MAX_RUNTIME_FLUSH_MINUTES);
48
49
  return {
49
50
  enabled,
@@ -51,11 +52,14 @@ export function loadRuntimeConfig(env = process.env) {
51
52
  token,
52
53
  projectId,
53
54
  organizationId: organizationIdRaw > 0 ? organizationIdRaw : null,
55
+ organizationSlug: organizationIdRaw > 0 ? null : organizationSlug,
54
56
  flushIntervalMs: flushMinutes * 60 * 1000,
55
57
  dryRun: envTruthy(env, 'NETGREENER_RUNTIME_DRY_RUN'),
56
58
  deployEnvironment: (env.NETGREENER_DEPLOY_ENVIRONMENT || env.DEPLOY_ENV || '').trim() || null,
57
- releaseTag: (env.NETGREENER_RELEASE_TAG || env.GIT_SHA || '').trim() || null,
58
- estimateTdpWatts: envNumberInRange(env, 'NETGREENER_ESTIMATE_TDP_WATTS', DEFAULT_ESTIMATE_TDP_WATTS, MIN_ESTIMATE_TDP_WATTS, MAX_ESTIMATE_TDP_WATTS),
59
+ // Release tag is NOT git SHA — SHA is attached separately on flush (anomaly evidence).
60
+ releaseTag: (env.NETGREENER_RELEASE_TAG || env.RELEASE_TAG || env.IMAGE_TAG || '').trim() || null,
61
+ // Prefer ESTIMATE_TDP; accept Python twin NETGREENER_CPU_TDP_WATTS as fallback.
62
+ estimateTdpWatts: envNumberInRange(env, 'NETGREENER_ESTIMATE_TDP_WATTS', envNumberInRange(env, 'NETGREENER_CPU_TDP_WATTS', DEFAULT_ESTIMATE_TDP_WATTS, MIN_ESTIMATE_TDP_WATTS, MAX_ESTIMATE_TDP_WATTS), MIN_ESTIMATE_TDP_WATTS, MAX_ESTIMATE_TDP_WATTS),
59
63
  tenantSource: (env.NETGREENER_TENANT_SOURCE || 'none').trim().toLowerCase(),
60
64
  tenantClaim: (env.NETGREENER_TENANT_CLAIM || 'organization_id').trim(),
61
65
  tenantHeader: (env.NETGREENER_TENANT_HEADER || 'X-Organization-Id').trim(),
@@ -1,5 +1,6 @@
1
1
  import type { RuntimeConfig } from './config.js';
2
2
  import { type RunSessionCreatePayload, type UploadResult } from './uploader.js';
3
+ import { type RuntimeLifecycle } from './lifecycle.js';
3
4
  export type ExportMode = 'direct' | 'collector' | 'thin';
4
5
  export type ExportResult = UploadResult & {
5
6
  mode: ExportMode;
@@ -52,5 +53,9 @@ export declare class CollectorRunSessionExporter implements ObservationExporter
52
53
  projectId?: number;
53
54
  }): Promise<ExportResult>;
54
55
  }
55
- export declare function resolveObservationExporter(env?: NodeJS.ProcessEnv): ObservationExporter;
56
- export declare function exportModeFromEnv(env?: NodeJS.ProcessEnv): ExportMode;
56
+ export declare function resolveObservationExporter(env?: NodeJS.ProcessEnv, opts?: {
57
+ lifecycle?: RuntimeLifecycle;
58
+ }): ObservationExporter;
59
+ export declare function exportModeFromEnv(env?: NodeJS.ProcessEnv, opts?: {
60
+ lifecycle?: RuntimeLifecycle;
61
+ }): ExportMode;