@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
@@ -0,0 +1,174 @@
1
+ /**
2
+ * Collect structured external-API declarations for Analyze output.
3
+ *
4
+ * Twin of Python ``declared_external_apis.py``: seeds the server catalog via
5
+ * ``POST /findings/batch`` when a caller uploads. Node Analyze CLI remains
6
+ * ``upload=never``; this only builds the payload (package.json + static imports).
7
+ *
8
+ * See ``docs/EXTERNAL_API_PR_TO_RELEASE.md``.
9
+ */
10
+ /**
11
+ * npm / import package roots → catalog ``provider_key``
12
+ * (aligned with Python ``_IMPORT_ROOT_TO_PROVIDER`` + server DEFAULT_PROVIDERS).
13
+ */
14
+ const PACKAGE_ROOT_TO_PROVIDER = {
15
+ openai: 'openai',
16
+ anthropic: 'anthropic',
17
+ '@anthropic-ai/sdk': 'anthropic',
18
+ stripe: 'stripe',
19
+ twilio: 'twilio',
20
+ sendgrid: 'sendgrid',
21
+ '@sendgrid/mail': 'sendgrid',
22
+ '@sendgrid/client': 'sendgrid',
23
+ boto3: 'boto3',
24
+ botocore: 'boto3',
25
+ google: 'google',
26
+ googleapis: 'google',
27
+ '@google/generative-ai': 'google',
28
+ '@google-cloud/vertexai': 'google',
29
+ generativelanguage: 'google',
30
+ cohere: 'cohere',
31
+ 'cohere-ai': 'cohere',
32
+ huggingface: 'huggingface',
33
+ '@huggingface/inference': 'huggingface',
34
+ '@huggingface/transformers': 'huggingface',
35
+ '@xenova/transformers': 'huggingface',
36
+ azure: 'azure_document_intelligence',
37
+ '@azure/ai-form-recognizer': 'azure_document_intelligence',
38
+ 'azure-ai-form-recognizer': 'azure_document_intelligence',
39
+ '@aws-sdk/client-textract': 'aws_textract',
40
+ };
41
+ /** Known paid roots used when map miss but name is still a paid SDK (Python PAID_API_MODULE_ROOTS twin). */
42
+ const PAID_PACKAGE_ROOTS = new Set([
43
+ ...Object.keys(PACKAGE_ROOT_TO_PROVIDER),
44
+ '@aws-sdk/client-bedrock-runtime',
45
+ '@aws-sdk/client-sagemaker-runtime',
46
+ ]);
47
+ const IMPORT_RE = /(?:from\s+['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)|import\s*\(\s*['"]([^'"]+)['"]\s*\))/g;
48
+ function normalizePackageRoot(spec) {
49
+ const text = String(spec || '')
50
+ .trim()
51
+ .replace(/\\/g, '/');
52
+ if (!text || text.startsWith('.') || text.startsWith('/') || text.startsWith('node:')) {
53
+ return '';
54
+ }
55
+ // Strip subpath: openai/resources → openai; @scope/pkg/sub → @scope/pkg
56
+ if (text.startsWith('@')) {
57
+ const parts = text.split('/');
58
+ if (parts.length >= 2)
59
+ return `${parts[0]}/${parts[1]}`.toLowerCase();
60
+ return text.toLowerCase();
61
+ }
62
+ return text.split('/')[0].toLowerCase();
63
+ }
64
+ function providerForPackageRoot(root) {
65
+ if (!root)
66
+ return null;
67
+ const mapped = PACKAGE_ROOT_TO_PROVIDER[root];
68
+ if (mapped)
69
+ return mapped;
70
+ if (root.startsWith('@aws-sdk/client-textract'))
71
+ return 'aws_textract';
72
+ if (root.startsWith('@aws-sdk/'))
73
+ return 'boto3';
74
+ if (root.startsWith('@google-cloud/'))
75
+ return 'google';
76
+ if (PAID_PACKAGE_ROOTS.has(root)) {
77
+ return PACKAGE_ROOT_TO_PROVIDER[root] ?? root.replace(/^@/, '').split('/')[0] ?? root;
78
+ }
79
+ return null;
80
+ }
81
+ function ensureRow(providers, providerKey) {
82
+ let row = providers.get(providerKey);
83
+ if (!row) {
84
+ row = {
85
+ provider_key: providerKey,
86
+ detection_methods: new Set(),
87
+ module_roots: new Set(),
88
+ file_paths: new Set(),
89
+ };
90
+ providers.set(providerKey, row);
91
+ }
92
+ return row;
93
+ }
94
+ function addPackage(providers, packageRoot, relPath, detectionMethod) {
95
+ const root = normalizePackageRoot(packageRoot);
96
+ const providerKey = providerForPackageRoot(root);
97
+ if (!providerKey)
98
+ return;
99
+ const row = ensureRow(providers, providerKey);
100
+ row.detection_methods.add(detectionMethod);
101
+ row.module_roots.add(root);
102
+ if (relPath)
103
+ row.file_paths.add(relPath.replace(/\\/g, '/'));
104
+ }
105
+ /** Extract package specs from JS/TS import / require / dynamic import. */
106
+ export function extractImportPackageRoots(source) {
107
+ const roots = new Set();
108
+ IMPORT_RE.lastIndex = 0;
109
+ let m;
110
+ while ((m = IMPORT_RE.exec(source)) != null) {
111
+ const spec = m[1] || m[2] || m[3] || '';
112
+ const root = normalizePackageRoot(spec);
113
+ if (root)
114
+ roots.add(root);
115
+ }
116
+ return [...roots];
117
+ }
118
+ /**
119
+ * Build ``declared_external_apis`` rows for analyze / findings-batch.
120
+ */
121
+ export function collectDeclaredExternalApis(input = {}) {
122
+ const providers = new Map();
123
+ const deps = input.packageDependencies;
124
+ if (deps && typeof deps === 'object') {
125
+ const pkgPath = (input.packageJsonPath || 'package.json').replace(/\\/g, '/');
126
+ for (const name of Object.keys(deps)) {
127
+ addPackage(providers, name, pkgPath, 'package_json');
128
+ }
129
+ }
130
+ const sources = input.sources;
131
+ if (sources && typeof sources === 'object') {
132
+ for (const [relPath, source] of Object.entries(sources)) {
133
+ if (typeof source !== 'string')
134
+ continue;
135
+ for (const root of extractImportPackageRoots(source)) {
136
+ addPackage(providers, root, relPath, 'static_import');
137
+ }
138
+ }
139
+ }
140
+ const out = [];
141
+ for (const key of [...providers.keys()].sort()) {
142
+ const row = providers.get(key);
143
+ // Prefer static_import when both package.json and source imports saw the provider.
144
+ const method = row.detection_methods.has('static_import')
145
+ ? 'static_import'
146
+ : row.detection_methods.has('package_json')
147
+ ? 'package_json'
148
+ : 'static_import';
149
+ out.push({
150
+ provider_key: row.provider_key,
151
+ detection_method: method,
152
+ module_roots: [...row.module_roots].sort(),
153
+ file_paths: [...row.file_paths].sort(),
154
+ });
155
+ }
156
+ return out;
157
+ }
158
+ /** Read dependency map from a package.json object. */
159
+ export function dependencyMapFromPackageJson(pkg) {
160
+ if (!pkg || typeof pkg !== 'object')
161
+ return null;
162
+ const o = pkg;
163
+ const out = {};
164
+ for (const key of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
165
+ const block = o[key];
166
+ if (!block || typeof block !== 'object')
167
+ continue;
168
+ for (const [name, ver] of Object.entries(block)) {
169
+ if (typeof name === 'string' && name)
170
+ out[name] = String(ver ?? '');
171
+ }
172
+ }
173
+ return Object.keys(out).length ? out : null;
174
+ }
@@ -13,3 +13,4 @@ export { isTypescriptAnalyzeAvailable, tryLoadTypescript, } from './loadTypescri
13
13
  export { allResourceFindingsValid, filterValidResourceFindings, validateResourceFindingCandidate, type ResourceFindingValidation, type ResourceFindingValidationError, } from './validateResourceFinding.js';
14
14
  export { buildAnalyzeGateSummary, countGateFindings, findingsExceedFailThreshold, formatAnalyzeGateFailureMessage, resolveAnalyzeGateLimit, type AnalyzeGateLimit, type AnalyzeGateSummaryV0, } from './analyzeGate.js';
15
15
  export { buildResourceAnalyzeResultFromPaths, buildResourceFindingsFromSources, type BuildResourceFindingsOptions, type ResourceAnalyzeResultV0, } from './buildResourceFindings.js';
16
+ export { collectDeclaredExternalApis, dependencyMapFromPackageJson, extractImportPackageRoots, type CollectDeclaredExternalApisInput, type DeclaredExternalApiEntry, } from './declaredExternalApis.js';
@@ -13,3 +13,4 @@ export { isTypescriptAnalyzeAvailable, tryLoadTypescript, } from './loadTypescri
13
13
  export { allResourceFindingsValid, filterValidResourceFindings, validateResourceFindingCandidate, } from './validateResourceFinding.js';
14
14
  export { buildAnalyzeGateSummary, countGateFindings, findingsExceedFailThreshold, formatAnalyzeGateFailureMessage, resolveAnalyzeGateLimit, } from './analyzeGate.js';
15
15
  export { buildResourceAnalyzeResultFromPaths, buildResourceFindingsFromSources, } from './buildResourceFindings.js';
16
+ export { collectDeclaredExternalApis, dependencyMapFromPackageJson, extractImportPackageRoots, } from './declaredExternalApis.js';
package/dist/auto.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Side-effect entry: ``import '@netgreener/runtime/auto'``.
3
+ * Starts NetGreener with runtime mode ``auto`` (persistent vs ephemeral).
4
+ */
5
+ import { NetGreener } from './init.js';
6
+ export { NetGreener };
7
+ export default NetGreener;
package/dist/auto.js ADDED
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Side-effect entry: ``import '@netgreener/runtime/auto'``.
3
+ * Starts NetGreener with runtime mode ``auto`` (persistent vs ephemeral).
4
+ */
5
+ import { NetGreener } from './init.js';
6
+ NetGreener.init({ runtime: 'auto' });
7
+ export { NetGreener };
8
+ export default NetGreener;
package/dist/bullmq.d.ts CHANGED
@@ -23,11 +23,11 @@ export type BullMqProcessorOptions = NetGreenerRuntimeOptions & {
23
23
  * - attributes outbound ``fetch`` to ``task:<job.name>``
24
24
  * - records a runtime task sample for flush
25
25
  */
26
- export declare function netgreenerBullMqProcessor<Job extends BullMqJobLike, Result>(processor: (job: Job) => Promise<Result> | Result, opts?: BullMqProcessorOptions): (job: Job) => Promise<Result>;
26
+ export declare function netgreenerBullMqProcessor<Job extends BullMqJobLike, Result>(processor: (job: Job) => Promise<Result> | Result, opts?: BullMqProcessorOptions): (job: Job) => Promise<Result> | Result;
27
27
  /**
28
28
  * Bind tenant + request attribution for one job without wrapping the whole Worker.
29
29
  * Useful when you already own the processor loop.
30
30
  */
31
- export declare function runBullMqJobWithNetGreener<Job extends BullMqJobLike, Result>(job: Job, fn: () => Promise<Result> | Result, opts?: BullMqProcessorOptions): Promise<Result>;
31
+ export declare function runBullMqJobWithNetGreener<Job extends BullMqJobLike, Result>(job: Job, fn: () => Promise<Result> | Result, opts?: BullMqProcessorOptions): Promise<Result> | Result;
32
32
  export declare function getBullMqRuntime(): NetGreenerRuntime;
33
33
  export type { TenantContext };
package/dist/bullmq.js CHANGED
@@ -6,9 +6,9 @@
6
6
  * kwarg) in ``job.data``.
7
7
  */
8
8
  import { getRuntime, } from './runtime.js';
9
- import { loadTenantConfig, resolveTenantFromTaskData, runWithTenantContext, } from './tenantContext.js';
9
+ import { resolveTenantFromTaskData, runWithTenantContext, tenantConfigFromRuntime, } from './tenantContext.js';
10
10
  import { runWithRequestAttribution } from './requestContext.js';
11
- import { beginProcessResourceSample, endProcessResourceSample, } from './processResources.js';
11
+ import { recordMeteredTask } from './taskMeter.js';
12
12
  function serviceUnitForJob(job, fallback) {
13
13
  const name = String(job.name || fallback || 'job').trim() || 'job';
14
14
  return `task:${name.slice(0, 240)}`;
@@ -26,38 +26,25 @@ export function netgreenerBullMqProcessor(processor, opts = {}) {
26
26
  ...opts,
27
27
  });
28
28
  runtime.start();
29
- const tenantConfig = loadTenantConfig();
29
+ const tenantConfig = tenantConfigFromRuntime(runtime.config);
30
30
  const fallbackName = opts.defaultJobName || 'job';
31
- return async function netgreenerInstrumentedProcessor(job) {
31
+ const tenantEnabled = tenantConfig.enabled;
32
+ return function netgreenerInstrumentedProcessor(job) {
32
33
  if (!runtime.enabled) {
33
- return await processor(job);
34
+ return processor(job);
34
35
  }
35
- const tenant = resolveTenantFromTaskData(job?.data && typeof job.data === 'object' ? job.data : null, tenantConfig);
36
+ const tenant = tenantEnabled
37
+ ? resolveTenantFromTaskData(job?.data && typeof job.data === 'object' ? job.data : null, tenantConfig)
38
+ : null;
36
39
  const serviceUnit = serviceUnitForJob(job, fallbackName);
37
- const started = performance.now();
38
- const resourceMark = beginProcessResourceSample();
39
- let error = false;
40
- const run = async () => {
41
- try {
42
- return await processor(job);
43
- }
44
- catch (err) {
45
- error = true;
46
- throw err;
47
- }
48
- finally {
49
- const resources = endProcessResourceSample(resourceMark);
50
- runtime.recordTask({
51
- serviceUnit,
52
- durationMs: performance.now() - started,
53
- error,
54
- tenantId: tenant?.tenantId ?? null,
55
- cpuTimeMs: resources.cpuTimeMs,
56
- peakRssKb: resources.rssKb,
57
- });
58
- }
59
- };
60
- return runWithTenantContext(tenant, () => runWithRequestAttribution({ serviceUnit }, () => run()));
40
+ const run = () => runWithRequestAttribution({ serviceUnit }, () => recordMeteredTask(runtime, {
41
+ serviceUnit,
42
+ tenantId: tenant?.tenantId ?? null,
43
+ taskId: job?.id != null ? String(job.id) : null,
44
+ fn: () => processor(job),
45
+ }));
46
+ // Skip empty tenant ALS when tenant source is disabled (still attributes outbound).
47
+ return tenantEnabled ? runWithTenantContext(tenant, run) : run();
61
48
  };
62
49
  }
63
50
  /**
@@ -71,35 +58,18 @@ export function runBullMqJobWithNetGreener(job, fn, opts = {}) {
71
58
  ...opts,
72
59
  });
73
60
  runtime.start();
74
- const tenantConfig = loadTenantConfig();
75
- const tenant = resolveTenantFromTaskData(job?.data && typeof job.data === 'object' ? job.data : null, tenantConfig);
61
+ const tenantConfig = tenantConfigFromRuntime(runtime.config);
62
+ const tenant = tenantConfig.enabled
63
+ ? resolveTenantFromTaskData(job?.data && typeof job.data === 'object' ? job.data : null, tenantConfig)
64
+ : null;
76
65
  const serviceUnit = serviceUnitForJob(job, opts.defaultJobName || 'job');
77
- const started = performance.now();
78
- const resourceMark = beginProcessResourceSample();
79
- let error = false;
80
- const run = async () => {
81
- try {
82
- return await fn();
83
- }
84
- catch (err) {
85
- error = true;
86
- throw err;
87
- }
88
- finally {
89
- if (runtime.enabled) {
90
- const resources = endProcessResourceSample(resourceMark);
91
- runtime.recordTask({
92
- serviceUnit,
93
- durationMs: performance.now() - started,
94
- error,
95
- tenantId: tenant?.tenantId ?? null,
96
- cpuTimeMs: resources.cpuTimeMs,
97
- peakRssKb: resources.rssKb,
98
- });
99
- }
100
- }
101
- };
102
- return runWithTenantContext(tenant, () => runWithRequestAttribution({ serviceUnit }, () => run()));
66
+ const run = () => runWithRequestAttribution({ serviceUnit }, () => recordMeteredTask(runtime, {
67
+ serviceUnit,
68
+ tenantId: tenant?.tenantId ?? null,
69
+ taskId: job?.id != null ? String(job.id) : null,
70
+ fn,
71
+ }));
72
+ return (tenantConfig.enabled ? runWithTenantContext(tenant, run) : run());
103
73
  }
104
74
  export function getBullMqRuntime() {
105
75
  return getRuntime({ collector: 'bullmq_worker', framework: 'bullmq' });
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Unified local-compute carbon ledger (Python ``carbon_ledger.py`` twin).
3
+ *
4
+ * Single formula for energy (kWh) → CO₂e with factor provenance.
5
+ * Vendor/catalog carbon stays separate.
6
+ */
7
+ export declare const DEFAULT_GRID_KG_CO2E_PER_KWH = 0.276;
8
+ export declare const FACTOR_VERSION = "v0";
9
+ export declare const FACTOR_UNIT = "kg_co2e_per_kwh";
10
+ export declare const DEFAULT_FACTOR_SOURCE = "netgreener_default_grid";
11
+ export type CarbonFactor = {
12
+ value: number;
13
+ unit: string;
14
+ source: string;
15
+ version: string;
16
+ location: string | null;
17
+ };
18
+ /** Resolve active grid intensity (env ``NETGREENER_CARBON_KG_PER_KWH`` overrides). */
19
+ export declare function defaultGridFactor(): CarbonFactor;
20
+ export declare function energyKwhToCarbonKg(energyKwh: number | null | undefined, factor?: CarbonFactor | null): {
21
+ carbonKg: number;
22
+ factor: CarbonFactor;
23
+ };
24
+ export declare function energyKwhToCarbonG(energyKwh: number | null | undefined, factor?: CarbonFactor | null): {
25
+ carbonG: number;
26
+ factor: CarbonFactor;
27
+ };
28
+ export declare function carbonFactorDict(factor?: CarbonFactor | null): CarbonFactor;
@@ -0,0 +1,52 @@
1
+ /**
2
+ * Unified local-compute carbon ledger (Python ``carbon_ledger.py`` twin).
3
+ *
4
+ * Single formula for energy (kWh) → CO₂e with factor provenance.
5
+ * Vendor/catalog carbon stays separate.
6
+ */
7
+ export const DEFAULT_GRID_KG_CO2E_PER_KWH = 0.276;
8
+ export const FACTOR_VERSION = 'v0';
9
+ export const FACTOR_UNIT = 'kg_co2e_per_kwh';
10
+ export const DEFAULT_FACTOR_SOURCE = 'netgreener_default_grid';
11
+ function envFloat(name) {
12
+ const raw = process.env[name];
13
+ if (raw == null || !String(raw).trim())
14
+ return null;
15
+ const n = Number(String(raw).trim());
16
+ return Number.isFinite(n) ? n : null;
17
+ }
18
+ /** Resolve active grid intensity (env ``NETGREENER_CARBON_KG_PER_KWH`` overrides). */
19
+ export function defaultGridFactor() {
20
+ const override = envFloat('NETGREENER_CARBON_KG_PER_KWH');
21
+ if (override != null && override >= 0) {
22
+ return {
23
+ value: override,
24
+ unit: FACTOR_UNIT,
25
+ source: 'env:NETGREENER_CARBON_KG_PER_KWH',
26
+ version: FACTOR_VERSION,
27
+ location: null,
28
+ };
29
+ }
30
+ return {
31
+ value: DEFAULT_GRID_KG_CO2E_PER_KWH,
32
+ unit: FACTOR_UNIT,
33
+ source: DEFAULT_FACTOR_SOURCE,
34
+ version: FACTOR_VERSION,
35
+ location: null,
36
+ };
37
+ }
38
+ export function energyKwhToCarbonKg(energyKwh, factor) {
39
+ const fac = factor ?? defaultGridFactor();
40
+ const energy = Number(energyKwh ?? 0);
41
+ if (!Number.isFinite(energy) || energy <= 0) {
42
+ return { carbonKg: 0, factor: fac };
43
+ }
44
+ return { carbonKg: energy * fac.value, factor: fac };
45
+ }
46
+ export function energyKwhToCarbonG(energyKwh, factor) {
47
+ const { carbonKg, factor: fac } = energyKwhToCarbonKg(energyKwh, factor);
48
+ return { carbonG: carbonKg * 1000, factor: fac };
49
+ }
50
+ export function carbonFactorDict(factor) {
51
+ return factor ?? defaultGridFactor();
52
+ }
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Linux cgroup v2 reader (Python ``cgroup_v2.CgroupV2Reader`` twin).
3
+ *
4
+ * Windows / non-Linux: ``available === false`` with an honest reason.
5
+ * Does not invent CPU/memory values. Injectable paths support unit tests.
6
+ */
7
+ export type CgroupV2Snapshot = {
8
+ cpu_usage_usec: number;
9
+ cpu_throttled_usec: number | null;
10
+ memory_current_bytes: number | null;
11
+ memory_peak_bytes: number | null;
12
+ memory_limit_bytes: number | null;
13
+ io_read_bytes: number | null;
14
+ io_write_bytes: number | null;
15
+ };
16
+ export type CgroupV2Provenance = {
17
+ schema_version: 1;
18
+ source: 'linux_cgroup_v2';
19
+ available: boolean;
20
+ path: string | null;
21
+ reason: string | null;
22
+ process_count: number | null;
23
+ shared_process_boundary: boolean | null;
24
+ };
25
+ export declare function resolveCgroupV2Path(procSelfCgroup: string, mountRoot?: string): string | null;
26
+ export type CgroupV2ReaderOptions = {
27
+ procSelfCgroupPath?: string;
28
+ mountRoot?: string;
29
+ /** Force platform detection (tests). */
30
+ platform?: NodeJS.Platform;
31
+ };
32
+ export declare class CgroupV2Reader {
33
+ readonly path: string | null;
34
+ readonly reason: string | null;
35
+ private readonly mountRoot;
36
+ constructor(opts?: CgroupV2ReaderOptions);
37
+ get available(): boolean;
38
+ private readFile;
39
+ private integerFile;
40
+ processCount(): number | null;
41
+ snapshot(): CgroupV2Snapshot | null;
42
+ provenance(): CgroupV2Provenance;
43
+ }
44
+ export declare function snapshotDelta(start: CgroupV2Snapshot, end: CgroupV2Snapshot): Record<string, number | null>;
@@ -0,0 +1,174 @@
1
+ /**
2
+ * Linux cgroup v2 reader (Python ``cgroup_v2.CgroupV2Reader`` twin).
3
+ *
4
+ * Windows / non-Linux: ``available === false`` with an honest reason.
5
+ * Does not invent CPU/memory values. Injectable paths support unit tests.
6
+ */
7
+ import { readFileSync, existsSync } from 'node:fs';
8
+ import { join } from 'node:path';
9
+ import { platform } from 'node:os';
10
+ function keyValues(text) {
11
+ const values = {};
12
+ for (const line of text.split(/\r?\n/)) {
13
+ const parts = line.trim().split(/\s+/);
14
+ if (parts.length === 2) {
15
+ const n = Number(parts[1]);
16
+ if (Number.isFinite(n))
17
+ values[parts[0]] = n;
18
+ }
19
+ }
20
+ return values;
21
+ }
22
+ function ioTotals(text) {
23
+ let read = 0;
24
+ let write = 0;
25
+ for (const line of text.split(/\r?\n/)) {
26
+ const tokens = line.trim().split(/\s+/).slice(1);
27
+ for (const token of tokens) {
28
+ const eq = token.indexOf('=');
29
+ if (eq < 0)
30
+ continue;
31
+ const key = token.slice(0, eq);
32
+ const amount = Number(token.slice(eq + 1));
33
+ if (!Number.isFinite(amount))
34
+ continue;
35
+ if (key === 'rbytes')
36
+ read += amount;
37
+ else if (key === 'wbytes')
38
+ write += amount;
39
+ }
40
+ }
41
+ return { read, write };
42
+ }
43
+ export function resolveCgroupV2Path(procSelfCgroup, mountRoot = '/sys/fs/cgroup') {
44
+ for (const line of procSelfCgroup.split(/\r?\n/)) {
45
+ const sep = line.indexOf('::');
46
+ if (sep < 0)
47
+ continue;
48
+ const hierarchy = line.slice(0, sep).trim();
49
+ if (hierarchy !== '0')
50
+ continue;
51
+ const relative = line.slice(sep + 2).trim().replace(/^\/+/, '');
52
+ return relative ? join(mountRoot, relative) : mountRoot;
53
+ }
54
+ return null;
55
+ }
56
+ export class CgroupV2Reader {
57
+ path;
58
+ reason;
59
+ mountRoot;
60
+ constructor(opts = {}) {
61
+ const plat = opts.platform ?? platform();
62
+ this.mountRoot = opts.mountRoot ?? '/sys/fs/cgroup';
63
+ const procPath = opts.procSelfCgroupPath ?? '/proc/self/cgroup';
64
+ if (plat !== 'linux') {
65
+ this.path = null;
66
+ this.reason = 'cgroup_v2_linux_only';
67
+ return;
68
+ }
69
+ try {
70
+ if (!existsSync(procPath)) {
71
+ this.path = null;
72
+ this.reason = 'proc_self_cgroup_unavailable';
73
+ return;
74
+ }
75
+ const content = readFileSync(procPath, 'utf8');
76
+ const resolved = resolveCgroupV2Path(content, this.mountRoot);
77
+ if (!resolved) {
78
+ this.path = null;
79
+ this.reason = 'unified_cgroup_v2_entry_not_found';
80
+ return;
81
+ }
82
+ if (!existsSync(join(resolved, 'cpu.stat'))) {
83
+ this.path = null;
84
+ this.reason = 'cpu_stat_unavailable';
85
+ return;
86
+ }
87
+ this.path = resolved;
88
+ this.reason = null;
89
+ }
90
+ catch {
91
+ this.path = null;
92
+ this.reason = 'proc_self_cgroup_unavailable';
93
+ }
94
+ }
95
+ get available() {
96
+ return this.path != null;
97
+ }
98
+ readFile(name) {
99
+ if (!this.path)
100
+ return null;
101
+ try {
102
+ return readFileSync(join(this.path, name), 'utf8').trim();
103
+ }
104
+ catch {
105
+ return null;
106
+ }
107
+ }
108
+ integerFile(name, unlimitedIsNone = false) {
109
+ const text = this.readFile(name);
110
+ if (text == null || (unlimitedIsNone && text === 'max'))
111
+ return null;
112
+ const n = Number(text);
113
+ return Number.isFinite(n) ? Math.max(0, n) : null;
114
+ }
115
+ processCount() {
116
+ const text = this.readFile('cgroup.procs');
117
+ if (text == null)
118
+ return null;
119
+ const pids = new Set();
120
+ for (const line of text.split(/\r?\n/)) {
121
+ const n = Number(line.trim());
122
+ if (Number.isFinite(n))
123
+ pids.add(n);
124
+ }
125
+ return pids.size > 0 ? pids.size : null;
126
+ }
127
+ snapshot() {
128
+ const cpuText = this.readFile('cpu.stat');
129
+ if (cpuText == null)
130
+ return null;
131
+ const cpu = keyValues(cpuText);
132
+ if (cpu.usage_usec == null)
133
+ return null;
134
+ const ioText = this.readFile('io.stat');
135
+ const io = ioText != null ? ioTotals(ioText) : null;
136
+ return {
137
+ cpu_usage_usec: cpu.usage_usec,
138
+ cpu_throttled_usec: cpu.throttled_usec ?? null,
139
+ memory_current_bytes: this.integerFile('memory.current'),
140
+ memory_peak_bytes: this.integerFile('memory.peak'),
141
+ memory_limit_bytes: this.integerFile('memory.max', true),
142
+ io_read_bytes: io?.read ?? null,
143
+ io_write_bytes: io?.write ?? null,
144
+ };
145
+ }
146
+ provenance() {
147
+ const process_count = this.available ? this.processCount() : null;
148
+ return {
149
+ schema_version: 1,
150
+ source: 'linux_cgroup_v2',
151
+ available: this.available,
152
+ path: this.path,
153
+ reason: this.reason,
154
+ process_count,
155
+ shared_process_boundary: process_count != null ? process_count > 1 : null,
156
+ };
157
+ }
158
+ }
159
+ export function snapshotDelta(start, end) {
160
+ const delta = (before, after) => {
161
+ if (before == null || after == null || after < before)
162
+ return null;
163
+ return after - before;
164
+ };
165
+ return {
166
+ cpu_usage_usec: delta(start.cpu_usage_usec, end.cpu_usage_usec),
167
+ cpu_throttled_usec: delta(start.cpu_throttled_usec, end.cpu_throttled_usec),
168
+ io_read_bytes: delta(start.io_read_bytes, end.io_read_bytes),
169
+ io_write_bytes: delta(start.io_write_bytes, end.io_write_bytes),
170
+ memory_current_bytes: end.memory_current_bytes,
171
+ memory_peak_bytes: end.memory_peak_bytes,
172
+ memory_limit_bytes: end.memory_limit_bytes,
173
+ };
174
+ }
@@ -1,8 +1,8 @@
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 declare const CLI_VERSION = "0.1.0";
4
+ export declare const CLI_VERSION = "0.1.8";
6
5
  export declare function formatRootHelp(): string;
7
6
  export declare function formatAnalyzeHelp(): string;
7
+ /** @deprecated Prefer formatOptimizeHelp / formatRunHelp. Kept for older tests. */
8
8
  export declare function formatStubHelp(command: 'run' | 'optimize'): string;