nexscope-cli 0.1.0__py3-none-any.whl

nexscope_cli/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Versioned Nexscope CLI and skill catalog."""
+__version__ = "0.1.0"

nexscope_cli/api-contract.json

@@ -0,0 +1,37 @@
+{
+  "version": "research-data-code-759d751.v1",
+  "backendRevision": "759d751b5cc43410c4f0b97014e0c4ddd9e366ce",
+  "verification": "source code and mock; no live samples",
+  "routes": {
+    "amazon-search": {
+      "research": "/api/v1/tools/research/amazon/search",
+      "skillApi": "/api/skill-api/v1/skills/amazon-search/run"
+    },
+    "amazon-product-detail": {
+      "research": "/api/v1/tools/research/amazon/product/detail",
+      "skillApi": "/api/skill-api/v1/skills/amazon-product-detail/run"
+    }
+  },
+  "response": {
+    "envelope": "ResponseData: code == 0 and data.products",
+    "reviewCount": "ratings",
+    "sourceUrl": [
+      "asinUrl",
+      "linkClean",
+      "link"
+    ],
+    "ratingScale": "unknown when absent",
+    "credits": "not response.cost; authoritative billing records",
+    "currency": "Three-letter codes can qualify prices; unqualified symbols are preserved as unresolved metadata, never inferred from marketplace."
+  },
+  "billing": {
+    "mechanism": "Server-side billing records and rules; no fixed client-side credit estimate.",
+    "fixedCredits": null,
+    "limits": "max-calls is not a monetary cap",
+    "searchEnrichment": "Not enabled in this data pilot."
+  },
+  "compatibility": {
+    "independentSkills": "NEXSCOPE_API_KEY + NEXSCOPE_PROXY_BASE unchanged",
+    "browserAccount": "OS keyring, no env fallback"
+  }
+}

nexscope_cli/capabilities/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Offline descriptions and plans for explicitly registered pilot capabilities."""

nexscope_cli/capabilities/catalog.py

@@ -0,0 +1,73 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""A1 planning subset of the pinned research routes, not a live API contract."""
+from copy import deepcopy
+from importlib.resources import files
+import json
+
+from ..core.errors import Failure
+
+DOMAINS = ('amazon.com', 'amazon.co.uk', 'amazon.de', 'amazon.fr', 'amazon.it',
+           'amazon.es', 'amazon.co.jp', 'amazon.ca', 'amazon.com.au', 'amazon.com.br',
+           'amazon.in', 'amazon.nl', 'amazon.se', 'amazon.pl', 'amazon.sg',
+           'amazon.sa', 'amazon.ae', 'amazon.com.mx', 'amazon.com.tr',
+           'amazon.com.be', 'amazon.cn', 'amazon.eg')
+COMMON = {
+    'amazonDomain': {'type': 'string', 'enum': list(DOMAINS), 'default': 'amazon.com'},
+    'language': {'type': 'string', 'minLength': 1, 'maxLength': 1000},
+    'deliveryZip': {'type': 'string', 'minLength': 1, 'maxLength': 1000},
+    'device': {'type': 'string', 'enum': ['desktop', 'mobile', 'tablet'], 'default': 'desktop'},
+}
+CAPABILITIES = {
+    'amazon-search': {
+        'endpoint': '/api/v1/tools/research/amazon/search',
+        'script': 'scripts/amazon_search.py',
+        'properties': {**COMMON,
+                       'keyword': {'type': 'string', 'minLength': 1, 'maxLength': 1024},
+                       'node': {'type': 'string', 'minLength': 1, 'maxLength': 1000},
+                       'page': {'type': 'integer', 'enum': [1], 'default': 1},
+                       'sort': {'type': 'string', 'enum': ['relevanceblender', 'price-asc-rank', 'price-desc-rank', 'review-rank', 'date-desc-rank', 'exact-aware-popularity-rank']}},
+        'required': [],
+        'anyOf': [{'required': ['keyword']}, {'required': ['node']}],
+        'limits': {'pages': 1, 'automaticPagination': False, 'requireKeywordOrNode': True},
+    },
+    'amazon-product-detail': {
+        'endpoint': '/api/v1/tools/research/amazon/product/detail',
+        'script': 'scripts/amazon_product_detail.py',
+        'properties': {**COMMON,
+                       'asins': {'type': 'string', 'pattern': '^[A-Z0-9]+(,[A-Z0-9]+){0,2}$', 'maxLength': 4096},
+                       'returnBoughtTogether': {'type': 'boolean'},
+                       'returnRelatedProducts': {'type': 'boolean'},
+                       'returnAuthorsReviews': {'type': 'boolean'}},
+        'required': ['asins'],
+        'limits': {'maxAsins': 3, 'requestStrategy': 'one-ASIN-per-request', 'duplicateAsins': 'reject'},
+    },
+}
+
+
+def describe(name):
+    if name not in CAPABILITIES:
+        raise Failure('Unknown capability; supported: amazon-search, amazon-product-detail.')
+    spec = deepcopy(CAPABILITIES[name])
+    bundled = json.loads(files('nexscope_cli').joinpath('catalog.json').read_text(encoding='utf-8'))
+    schema = {'type': 'object', 'additionalProperties': False,
+              'properties': spec['properties'], 'required': spec['required']}
+    if 'anyOf' in spec:
+        schema['anyOf'] = spec['anyOf']
+    return {
+        'schemaVersion': 'nexscope.capability.v1', 'capability': name,
+        'contractVersion': 'research-data-code-759d751.v1', 'status': 'EXECUTION_GATED',
+        'executionAvailable': False, 'liveExecutionAvailable': True,
+        'executionRequires': ['--execute', '--allow-paid'],
+        'mockExecutionAvailable': True, 'method': 'POST', 'endpoint': spec['endpoint'],
+        'inputSchema': schema, 'pilotLimits': spec['limits'],
+        'source': {'skill': name, 'script': spec['script'],
+                   'repository': bundled['source'], 'revision': bundled['skills'][name].get('sourceRevision', bundled['revision']),
+                   'snapshot': bundled['skills'][name].get('sourceSnapshot'),
+                   'reference': 'references/api.md',
+                   'sha256': bundled['skills'][name]['files']['references/api.md']},
+        'validation': 'Pinned backend source and mock verified; live samples and billing acceptance remain pending.',
+        'contract': json.loads(files('nexscope_cli').joinpath('api-contract.json').read_text(encoding='utf-8')),
+        'pricing': {'status': 'UNKNOWN', 'creditsPerRequest': None,
+                    'source': None, 'note': 'Response cost is elapsed time, not credits.'},
+    }

nexscope_cli/capabilities/mock.py

@@ -0,0 +1,53 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Deterministic, explicitly fictional fixtures. Never imports a network client."""
+from copy import deepcopy
+from importlib.resources import files
+import json
+
+from ..core.auth import AuthContext
+from ..core.errors import Failure
+from ..core.execution import Executor
+
+SCENARIOS = ('complete', 'partial', 'empty', 'unauthorized', 'credits', 'rate-limit', 'timeout', 'malformed')
+
+
+class MockTransport:
+    def __init__(self, scenario='complete'):
+        if scenario not in SCENARIOS:
+            raise Failure('Unknown mock scenario.')
+        self.scenario, self.calls = scenario, []
+        self.cache_namespace = 'fictional-v1:' + scenario
+        self.fixture = json.loads(files('nexscope_cli.resources').joinpath('mock-products.json').read_text(encoding='utf-8'))
+
+    def send(self, context, endpoint, body):
+        self.calls.append((endpoint, deepcopy(body)))
+        if self.scenario == 'timeout':
+            raise TimeoutError('Fixture timeout')
+        if self.scenario == 'unauthorized':
+            return 401, {'code': 12003, 'data': None}
+        if self.scenario == 'credits':
+            return 200, {'code': 13011, 'data': None}
+        if self.scenario == 'rate-limit':
+            return 429, {'code': 429, 'data': None}
+        if self.scenario == 'malformed':
+            return 200, {'code': '0', 'data': None}
+        if self.scenario == 'empty':
+            return 200, {'code': 0, 'data': {'products': []}}
+        rows = deepcopy(self.fixture['products'])
+        if endpoint.endswith('/product/detail'):
+            if self.scenario == 'partial' and body['asins'] == 'B000000002':
+                return 200, {'code': 0, 'data': {'products': []}}
+            index = sum(map(ord, body['asins'])) % len(rows)
+            row = next((row for row in rows if row['asin'] == body['asins']), rows[index])
+            row['asin'] = body['asins']
+            row['link'] = 'https://example.invalid/product/' + body['asins']
+            rows = [row]
+        return 200, {'code': 0, 'msg': None, 'data': {'products': rows}, 'cost': '12'}
+
+
+def executor(mode, scenario, max_calls):
+    # Fake credentials are generated internally; inherited keys and keyring are
+    # deliberately not accessed, even when the requested mode is browser-account.
+    context = AuthContext(mode, 'https://mock.invalid', 'fictional-context-only')
+    return Executor(context, MockTransport(scenario), max_calls=max_calls)

nexscope_cli/capabilities/plan.py

@@ -0,0 +1,142 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Pure, bounded request planning. No credential, cache, or transport access."""
+import hashlib
+import json
+from pathlib import Path
+import re
+
+from .catalog import describe
+from ..core.auth import DEFAULT_ORIGIN, MODES, origin
+from ..core.errors import Failure
+
+MAX_INPUT_BYTES = 64 * 1024
+
+
+def read_input(path):
+    with Path(path).open('rb') as stream:
+        raw = stream.read(MAX_INPUT_BYTES + 1)
+    if len(raw) > MAX_INPUT_BYTES:
+        raise Failure('Plan input exceeds 64 KiB.')
+
+    def unique(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ValueError
+            result[key] = value
+        return result
+
+    def reject_constant(value):
+        raise ValueError
+
+    try:
+        params = json.loads(raw.decode('utf-8-sig'), object_pairs_hook=unique,
+                            parse_constant=reject_constant)
+    except (UnicodeError, ValueError, RecursionError):
+        raise Failure('Plan input must be UTF-8 JSON without duplicate keys or non-finite values.') from None
+    return params, hashlib.sha256(raw).hexdigest()
+
+
+def normalize(params, description):
+    schema = description['inputSchema']
+    if not isinstance(params, dict):
+        raise Failure('Plan input must be a JSON object.')
+    # Do not echo unknown fields or invalid values: they may contain secrets.
+    if set(params) - set(schema['properties']):
+        raise Failure('Unsupported parameter; use capabilities describe for allowed fields.')
+    if any(key not in params for key in schema['required']):
+        raise Failure('Missing required parameters; use capabilities describe.')
+    result = {}
+    for key, rule in schema['properties'].items():
+        if key not in params:
+            if 'default' in rule:
+                result[key] = rule['default']
+            continue
+        value = params[key]
+        valid = True
+        if rule['type'] == 'string':
+            valid = isinstance(value, str) and bool(value.strip()) and not any(ord(c) < 32 for c in value)
+            if valid:
+                valid = len(value) <= rule.get('maxLength', 1000)
+                if 'pattern' in rule:
+                    valid = valid and re.fullmatch(rule['pattern'], value) is not None
+        elif rule['type'] == 'integer':
+            valid = type(value) is int
+        elif rule['type'] == 'boolean':
+            valid = type(value) is bool
+        if not valid or ('enum' in rule and value not in rule['enum']):
+            raise Failure('Invalid parameter: ' + key + '; see the planning input schema.')
+        result[key] = value
+    if description['capability'] == 'amazon-search' and not any(k in result for k in ('keyword', 'node')):
+        raise Failure('The search pilot requires keyword or node.')
+    if 'asins' in result:
+        asins = result['asins'].split(',')
+        if len(set(asins)) != len(asins):
+            raise Failure('Duplicate ASINs are not allowed in the detail plan.')
+    return result
+
+
+def plan(name, params, *, auth_mode='browser-account', api_base=None, max_calls=3):
+    description = describe(name)
+    if auth_mode not in MODES:
+        raise Failure('Choose an explicit supported authentication mode.')
+    if type(max_calls) is not int or max_calls < 1:
+        raise Failure('max-calls must be a positive integer.')
+    if auth_mode == 'env-api-key' and api_base is not None:
+        raise Failure('env-api-key resolves NEXSCOPE_PROXY_BASE at execution; omit --api-base.')
+    params = normalize(params, description)
+    bodies = [dict(params, asins=asin) for asin in params['asins'].split(',')] if name == 'amazon-product-detail' else [params]
+    if len(bodies) > max_calls:
+        raise Failure('Request count exceeds max-calls; no requests were sent.')
+    selected_origin = origin(api_base if api_base is not None else DEFAULT_ORIGIN) if auth_mode == 'browser-account' else None
+    return {
+        'schemaVersion': 'nexscope.plan.v1', 'status': 'PLANNED',
+        'capability': name, 'contractVersion': description['contractVersion'],
+        'source': description['source'], 'executionAvailable': False,
+        'auth': {'mode': auth_mode, 'origin': selected_origin,
+                 'originSource': '--api-base or default' if selected_origin else 'NEXSCOPE_PROXY_BASE at execution',
+                 'credentialsRead': False},
+        'requests': [{'sequence': i + 1, 'method': 'POST', 'endpoint': description['endpoint'], 'body': body}
+                     for i, body in enumerate(bodies)],
+        'budget': {'scope': 'data-api-requests-only', 'maxCalls': max_calls, 'plannedRequests': len(bodies),
+                   'maximumRequests': len(bodies), 'requestsSent': 0,
+                   'automaticRetries': 0, 'estimatedCredits': None,
+                   'billingCap': None, 'pricingStatus': 'UNKNOWN', 'pricingSource': None,
+                   'note': 'Request bounds are not a monetary or server billing cap.'},
+        'cache': {'policy': 'no-cache-read-or-write', 'assumedHits': 0},
+        'warnings': ['Remote execution requires explicit --execute --allow-paid; mock never reads credentials.',
+                     'No automatic pagination, ASIN expansion, or fallback authentication.'],
+    }
+
+
+def command(args):
+    if args.execute and not args.mock and not args.allow_paid:
+        raise Failure('EXECUTION_UNAVAILABLE: choose --mock or explicitly authorize remote scope with --allow-paid.')
+    params, digest = read_input(args.input)
+    result = plan(args.capability, params, auth_mode=args.auth_mode,
+                  api_base=args.api_base, max_calls=args.max_calls)
+    result['inputSha256'] = digest
+    if args.execute:
+        if args.mock and args.api_base is not None:
+            raise Failure('Mock execution uses a fictional origin; omit --api-base.')
+        if not args.out:
+            raise Failure('Choose a new output directory with --out.')
+        from ..core.remote import engine_for
+        if args.mock and args.allow_paid:
+            raise Failure('Choose mock execution or paid execution, not both.')
+        source_type = 'mock' if args.mock else 'remote'
+        from ..core.evidence import Artifacts
+        engine = engine_for(args)
+        result['execution'] = {'sourceType': source_type, 'origin': engine.context.base, 'requestsSent': 0}
+        result['auth'].update(origin=engine.context.base, originSource='selected execution context')
+        artifacts = Artifacts(args.out, result)
+        engine.record = artifacts.record
+        requests = engine.execute(args.capability, params)
+        successes = sum(r['status'] == 'SUCCESS' for r in requests)
+        result = {'status': 'COMPLETE' if successes == len(requests) else ('PARTIAL' if successes else 'FAILED'),
+                  'sourceType': source_type, 'output': str(artifacts.root), 'requests': requests,
+                  'budget': engine.summary(), 'liveRequests': 0 if args.mock else engine.sent}
+        artifacts.write('result.json', dict(result, output='.'))
+        artifacts.finish()
+    return result

nexscope_cli/catalog.json

@@ -0,0 +1,69 @@
+{
+  "source": "https://github.com/nexscope-ai/nexscope-ecommerce-skills",
+  "revision": "cd532d33ce21a643f9945e05ca556b5ba890813d",
+  "skills": {
+    "amazon-search": {
+      "source": "ecommerce-amazon-search",
+      "description": "Search Amazon products.",
+      "scripts": [
+        "scripts/amazon_search.py"
+      ],
+      "files": {
+        "SKILL.md": "90412bcf6070a0699593b028526421d396758f1f07065c897e03541175fe710c",
+        "references/api.md": "ac2f6764ddafbd4ab0e19cb5f3cfe37838ebd76879c604ad62c40a4dcd6e77ea",
+        "requirements.txt": "f2c92b444b157b26b21266f4d3ef6f5e3249771346999a7d8edd064bd215c3e9",
+        "scripts/amazon_search.py": "569ef7f00545dfba52bb5d7f1239c08ce8aa9ec3003ae361dea3c3d585bc3c2d"
+      },
+      "available": true,
+      "sourceRevision": "742ccef80fc605842b0249864051e4f690adcabb",
+      "sourceSnapshot": {
+        "state": "local-candidate-not-a-release",
+        "manifestSha256": "939192eb79d205008548d54397efe2be63bcfcb32811c414ddf5af68dfc83dd3",
+        "files": {
+          "SKILL.md": "d4f3cde82fcb8855d2167633764bd3c765ed3b6ad824116b9ee0a7d05254f3d7",
+          "references/api.md": "ac2f6764ddafbd4ab0e19cb5f3cfe37838ebd76879c604ad62c40a4dcd6e77ea",
+          "requirements.txt": "5d007fcd9e56e8319c5eddb055bddffe26305dac70d771526a130ac8ae17d3a8",
+          "scripts/amazon_search.py": "5036600ddc06ed2a333fb2e8b6b76b84d7968ba109dcedd4a3c1bd4ce46d174b"
+        }
+      },
+      "distributionTransforms": [
+        "Nexscope copyright and Apache-2.0 SPDX headers added for approved data-only distribution",
+        "Standalone CLI 0.1.2.dev8 adapter version and installation instructions; historical sourceSnapshot unchanged",
+        "Standalone CLI 0.1.2.dev11 pins; unqualified currency symbols retained as unresolved metadata without inferring an ISO code",
+        "Standalone CLI 0.1.0 initial independent version; paired adapter pins updated"
+      ]
+    },
+    "amazon-product-detail": {
+      "source": "ecommerce-amazon-product-detail",
+      "description": "Retrieve Amazon product details.",
+      "scripts": [
+        "scripts/amazon_product_detail.py"
+      ],
+      "files": {
+        "SKILL.md": "911982d386dfd2c63936f6e307f0dfc69e1489ff24d342310cbd4600146d17ff",
+        "references/api.md": "2ad537d7861e650a1ec195791e7aa488614132e1305473c53af0c7a63f4d0d59",
+        "requirements.txt": "f2c92b444b157b26b21266f4d3ef6f5e3249771346999a7d8edd064bd215c3e9",
+        "scripts/amazon_product_detail.py": "cf7eaea94865a6e7c9dc727fe5e4f8000ac91a67c8a4e4edbe618ac84b2de6e9"
+      },
+      "available": true,
+      "sourceRevision": "742ccef80fc605842b0249864051e4f690adcabb",
+      "sourceSnapshot": {
+        "state": "local-candidate-not-a-release",
+        "manifestSha256": "b688700d08cec44ab8fb1d6b9692e2a974dbb02412aad128bf49deefb493ec22",
+        "files": {
+          "SKILL.md": "69958b1b48ad00cb6061ab0084bec6f27e1ae62e242db4da6768f567efc849d9",
+          "references/api.md": "2ad537d7861e650a1ec195791e7aa488614132e1305473c53af0c7a63f4d0d59",
+          "requirements.txt": "5d007fcd9e56e8319c5eddb055bddffe26305dac70d771526a130ac8ae17d3a8",
+          "scripts/amazon_product_detail.py": "56ce266fbd21b9c837915d766eb3c907cdcba1708097c47c62fa45d1f3f9ffdc"
+        }
+      },
+      "distributionTransforms": [
+        "Nexscope copyright and Apache-2.0 SPDX headers added for approved data-only distribution",
+        "Standalone CLI 0.1.2.dev8 adapter version and installation instructions; historical sourceSnapshot unchanged",
+        "Standalone CLI 0.1.2.dev11 pins; unqualified currency symbols retained as unresolved metadata without inferring an ISO code",
+        "Standalone CLI 0.1.0 initial independent version; paired adapter pins updated"
+      ]
+    }
+  },
+  "distributionProfile": "data-only"
+}

nexscope_cli/compat/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Versioned compatibility API for independent Skill entrypoints."""
+COMPAT_API_VERSION = 1

nexscope_cli/compat/legacy.py

@@ -0,0 +1,143 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Preserve standalone JSON/flags/environment access without pilot scope limits."""
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import time
+
+from ..core.auth import resolve_auth
+from ..core.errors import Failure
+from ..core.execution import SessionCache, redact, validate_response
+from ..core.transport import HttpTransport
+
+CAPABILITIES = {
+    'amazon-search': ('/api/v1/tools/research/amazon/search', 'ecommerce.amazon-search-amazon_search'),
+    'amazon-product-detail': ('/api/v1/tools/research/amazon/product/detail', 'ecommerce.amazon-product-detail-amazon_product_detail'),
+}
+
+
+class LegacySession:
+    """A new session snapshots the explicitly selected environment credentials.
+
+    The legacy input object is sent once, unchanged. Do not apply the pilot's
+    one-page/three-ASIN planner, split batches, or add default request fields.
+    """
+    def __init__(self, context, transport=None, cache=None):
+        if context.mode != 'env-api-key':
+            raise Failure('Independent Skills require an explicit env-api-key context.')
+        self.context = context
+        self.transport = transport if transport is not None else HttpTransport()
+        self.cache = cache if cache is not None else SessionCache()
+
+    def call(self, capability, params, use_cache=True):
+        if capability not in CAPABILITIES or not isinstance(params, dict):
+            raise Failure('Use a registered legacy Skill and a JSON object.')
+        canonical = json.dumps(params, sort_keys=True, allow_nan=False)
+        key = (self.context.cache_partition, self.transport.cache_namespace,
+               'legacy-envelope.v1', capability, canonical)
+        cached = self.cache.get(key) if use_cache else None
+        if cached is not None:
+            payload = cached['payload']
+            metadata = payload.get('_cache')
+            payload['_cache'] = {**(metadata if isinstance(metadata, dict) else {}), 'hit': True,
+                                 'fetchedAt': cached['fetchedAt']}
+            return payload
+        status, payload = self.transport.send(self.context, CAPABILITIES[capability][0], params)
+        if not isinstance(payload, dict):
+            payload = {'error': 'HTTP ' + str(status) + ': response is not a JSON object'}
+        payload = redact(payload, self.context)
+        # Cache only the response subset already validated by the common core.
+        # Use the common envelope/product checks, not the pilot detail check
+        # (which assumes a single ASIN and would reject legacy batches).
+        # Unknown valid server shapes are still returned unchanged, never guessed.
+        error, stop = validate_response(status, payload, 'amazon-search', params)
+        if stop:
+            self.cache.invalidate(self.context.cache_partition)
+        if use_cache and error is None:
+            self.cache.put(key, {'payload': payload,
+                                'fetchedAt': datetime.fromtimestamp(self.cache.clock(), timezone.utc).isoformat()})
+        return payload
+
+
+def largest_list(value, prefix=''):
+    if isinstance(value, list):
+        return prefix, len(value), value
+    best = (None, -1, None)
+    if isinstance(value, dict):
+        for key, child in value.items():
+            found = largest_list(child, prefix + '.' + key if prefix else key)
+            if found[1] > best[1]:
+                best = found
+    return best
+
+
+def summarize(result):
+    print('Top-level keys: ' + str(list(result)))
+    for key in ('errcode', 'code', 'errmsg', 'msg', 'total', 'count', 'costToken', 'costTime'):
+        if isinstance(result.get(key), (int, float, bool, str)):
+            print('  ' + key + ': ' + str(result[key]))
+    path, count, rows = largest_list(result)
+    if path and rows:
+        print('\nLongest list: `' + path + '` (' + str(count) + ' items)')
+        print('First ' + str(min(3, count)) + ':')
+        print(json.dumps(rows[:3], ensure_ascii=False, indent=2))
+
+
+def output_path(capability):
+    moment = datetime.now()
+    session = os.environ.get('SESSION_ID', '').strip() or moment.strftime('%H%M%S')
+    if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,127}', session):
+        raise Failure('SESSION_ID must be a safe directory name (letters, digits, dot, underscore, dash).')
+    root = Path.cwd().resolve()
+    folder = root / 'nexscope' / moment.strftime('%Y-%m-%d') / session / 'data'
+    if not folder.resolve().is_relative_to(root):
+        raise Failure('Output must remain inside the working directory.')
+    folder.mkdir(parents=True, exist_ok=True)
+    if not folder.resolve().is_relative_to(root):
+        raise Failure('Output must remain inside the working directory.')
+    return folder / (CAPABILITIES[capability][1] + '-' + str(time.time_ns() // 1000) + '.json')
+
+
+def main(capability, argv=None):
+    args = sys.argv[1:] if argv is None else list(argv)
+    options = [arg for arg in args if arg not in ('--inline', '--no-cache')]
+    if len(options) != 1:
+        print("Usage: python script.py '<JSON params>' [--inline] [--no-cache]", file=sys.stderr)
+        return 1
+    target = None
+    created = False
+    try:
+        def reject(value):
+            raise ValueError('Non-finite JSON values are not supported.')
+        params = json.loads(options[0], parse_constant=reject)
+        if not isinstance(params, dict) or capability not in CAPABILITIES:
+            raise Failure('Params must be a JSON object for a registered Skill.')
+        context = resolve_auth('env-api-key')
+        target = output_path(capability)
+        # Reserve output before requesting data; never fall back to home or temp.
+        with target.open('x', encoding='utf-8') as stream:
+            created = True
+            session = LegacySession(context)
+            result = session.call(capability, params, use_cache='--no-cache' not in args)
+            serialized = json.dumps(result, ensure_ascii=False, allow_nan=False)
+            json.dump(result, stream, ensure_ascii=False, indent=2, allow_nan=False)
+        print('Saved full response: ' + str(target) + ' (' + str(len(serialized)) + ' bytes)')
+        if isinstance(result.get('_cache'), dict) and result['_cache'].get('hit'):
+            print('Cache hit')
+        if '--inline' in args or len(serialized.encode('utf-8')) <= 8000:
+            print(serialized)
+        else:
+            summarize(result)
+        # Retain legacy behavior: JSON business errors are output, not rewrapped.
+        # Callers must inspect outer code/error, not infer success from exit zero.
+        return 0
+    except Exception as error:
+        if created and target is not None and target.exists() and target.stat().st_size == 0:
+            target.unlink()
+        message = str(error) if isinstance(error, Failure) else 'Operation failed (' + type(error).__name__ + '); no automatic retry.'
+        print(message, file=sys.stderr)
+        return 1

nexscope_cli/core/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Shared, credential-free dataset primitives."""

nexscope_cli/core/auth.py

@@ -0,0 +1,81 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Explicit, immutable authentication snapshots; never discover a fallback."""
+from dataclasses import dataclass, field
+import os
+from urllib.parse import urlsplit
+import uuid
+
+from .errors import AuthRequired, Failure
+
+MODES = ('browser-account', 'env-api-key')
+DEFAULT_ORIGIN = 'https://api.nexscope.ai'
+
+
+def origin(value):
+    try:
+        if not isinstance(value, str) or any(c.isspace() or ord(c) < 32 for c in value):
+            raise ValueError
+        p = urlsplit(value)
+        if (p.scheme != 'https' and not (p.scheme == 'http' and p.hostname in ('localhost', '127.0.0.1'))) or not p.hostname or p.username or p.password or p.query or p.fragment or p.path not in ('', '/'):
+            raise ValueError
+        # Validate malformed ports before a request can contain a credential.
+        p.port
+    except ValueError:
+        raise Failure('Use an HTTPS API origin (HTTP is allowed only on loopback).') from None
+    return value.rstrip('/')
+
+
+@dataclass(frozen=True)
+class AuthContext:
+    mode: str
+    base: str
+    _key: str = field(repr=False)
+    _session: str = field(default_factory=lambda: uuid.uuid4().hex, repr=False)
+
+    def __post_init__(self):
+        if self.mode not in MODES:
+            raise Failure('Choose an explicit supported authentication mode.')
+        object.__setattr__(self, 'base', origin(self.base))
+        if not isinstance(self._key, str) or not self._key or any(c.isspace() or ord(c) < 32 for c in self._key):
+            raise AuthRequired('AUTH_REQUIRED: the selected context has no valid API key.')
+
+    def authorization(self):
+        """Secret-bearing value: only pass to the selected origin's transport."""
+        return 'Bearer ' + self._key
+
+    def script_environment(self, inherited=None):
+        """Pass credentials only to a child process, never persist this mapping."""
+        env = dict(os.environ if inherited is None else inherited)
+        env.update(NEXSCOPE_API_KEY=self._key, NEXSCOPE_PROXY_BASE=self.base)
+        env.pop('PYTHONPATH', None)
+        return env
+
+    def redact(self, text):
+        return text.replace(self._key, '[REDACTED]')
+
+    @property
+    def cache_partition(self):
+        # A1 has no shared persistent cache. New snapshots never share a session,
+        # even when keys rotate or two accounts use the same origin/profile.
+        return self.mode, self.base, self._session
+
+
+def resolve_auth(mode, *, base=None, credential_loader=None, environment=None):
+    """Resolve just the selected source. Offline planning must not call this."""
+    if mode == 'browser-account':
+        selected_base = origin(base if base is not None else DEFAULT_ORIGIN)
+        credential = credential_loader() if credential_loader is not None else None
+        if not isinstance(credential, dict) or not credential.get('apiKey'):
+            raise AuthRequired('AUTH_REQUIRED: run nexscope auth login.')
+        return AuthContext(mode, selected_base, credential['apiKey'])
+    if mode == 'env-api-key':
+        if base is not None:
+            raise Failure('env-api-key uses NEXSCOPE_PROXY_BASE; do not supply a browser API origin.')
+        env = os.environ if environment is None else environment
+        key = env.get('NEXSCOPE_API_KEY', '').strip()
+        selected_base = env.get('NEXSCOPE_PROXY_BASE', '').strip()
+        if not key or not selected_base:
+            raise AuthRequired('AUTH_REQUIRED: configure NEXSCOPE_API_KEY and NEXSCOPE_PROXY_BASE.')
+        return AuthContext(mode, selected_base, key)
+    raise Failure('Choose an explicit supported authentication mode.')