nexscope-cli 0.1.0__py3-none-any.whl

nexscope_cli/main.py

@@ -0,0 +1,313 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Independent, OS-keyring-backed Nexscope CLI. Never prints credentials."""
+import argparse
+import csv
+import json
+from pathlib import Path
+import subprocess
+import sys
+import uuid
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, build_opener, HTTPRedirectHandler
+
+from . import __version__
+from .core.datasets import DatasetError
+from .core.auth import DEFAULT_ORIGIN, MODES, origin, resolve_auth
+from .core.errors import AuthRequired, Failure
+
+ROOT = Path(__file__).parent
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        raise Failure('Redirect refused; check the API origin.')
+
+
+class Client:
+    def __init__(self, base):
+        self.base = origin(base)
+        import keyring
+        backend = keyring.get_keyring()
+        # Fail closed: do not fall back to plaintext files or inherited API keys.
+        module = type(backend).__module__
+        if module not in ('keyring.backends.macOS', 'keyring.backends.Windows', 'keyring.backends.SecretService', 'keyring.backends.kwallet'):
+            raise Failure('An OS credential store is required. Configure a supported keyring backend.')
+        self.store = backend
+        self.service = 'nexscope-cli:' + self.base
+
+    def load(self, name):
+        raw = self.store.get_password(self.service, name)
+        return json.loads(raw) if raw else None
+
+    def save(self, name, value):
+        self.store.set_password(self.service, name, json.dumps(value))
+
+    def clear(self, name):
+        if self.load(name) is not None:
+            self.store.delete_password(self.service, name)
+
+    def api(self, path, body=None, authenticated=False, context=None):
+        headers = {'Accept': 'application/json', 'Content-Type': 'application/json'}
+        if authenticated:
+            context = context or resolve_auth('browser-account', base=self.base, credential_loader=lambda: self.load('credential'))
+            if context.mode != 'browser-account' or context.base != self.base:
+                raise Failure('Browser API requires its own origin-bound browser-account context.')
+            headers['Authorization'] = context.authorization()
+        req = Request(self.base + '/api/cli/' + path, data=None if body is None else json.dumps(body).encode(), headers=headers)
+        try:
+            with build_opener(NoRedirect()).open(req, timeout=30) as response:
+                result = json.load(response)
+        except HTTPError as e:
+            e.close()
+            if e.code == 401 and authenticated:
+                raise AuthRequired('AUTH_REQUIRED: reconnect with nexscope auth login.') from None
+            raise Failure(f'HTTP {e.code}; request not retried.') from None
+        except (URLError, TimeoutError):
+            raise Failure('Network unavailable; request not retried.') from None
+        if not isinstance(result, dict):
+            raise Failure('Invalid API response.')
+        if result.get('code') in (12001, 12003):
+            raise AuthRequired('AUTH_REQUIRED: reconnect with nexscope auth login.')
+        if result.get('code') != 0:
+            raise Failure(f"API error {result.get('code')}; request not retried.")
+        return result.get('data')
+
+    def auth(self, action, attribution=None):
+        if action == 'login':
+            if self.load('credential'):
+                try:
+                    return self.api('account', authenticated=True)
+                except AuthRequired:
+                    self.clear('credential')
+            pending = self.load('pending')
+            import time
+            if not pending or int(pending['expiresAt']) <= time.time() * 1000:
+                pending = self.api('auth/start', {} if attribution is None else {'attribution': attribution})
+                self.save('pending', pending)
+            return {k: v for k, v in pending.items() if k != 'pollSecret'}
+        if action == 'poll':
+            pending = self.load('pending')
+            if not pending:
+                return self.api('account', authenticated=True)
+            body = {k: pending[k] for k in ('requestId', 'pollSecret')}
+            value = self.api('auth/poll', body)
+            if value['status'] == 'READY':
+                self.save('credential', value)
+                self.api('auth/poll', {**body, 'acknowledge': True})
+                self.clear('pending')
+                return self.api('account', authenticated=True)
+            if value['status'] in ('DENIED', 'AUTH_EXPIRED', 'CONNECTED'):
+                self.clear('pending')
+            return {k: v for k, v in value.items() if k != 'apiKey'}
+        if action == 'logout':
+            if self.load('credential'):
+                self.api('disconnect', {}, authenticated=True)
+            self.clear('credential')
+            self.clear('pending')
+            return {'status': 'DISCONNECTED'}
+        return self.api('account', authenticated=True)
+
+
+def catalog():
+    return json.loads((ROOT / 'catalog.json').read_text())['skills']
+
+
+def guide(name):
+    skills = catalog()
+    if name == 'core':
+        return {'version': __version__, 'skills': {k: v['description'] for k, v in skills.items() if v.get('available', True)},
+                'unavailable': {k: v['unavailable'] for k, v in skills.items() if not v.get('available', True)},
+                'execution': 'Read get-skills <name>; use run <name> [--script path] -- <script arguments>. Never run packaged scripts directly. Auth: login, user done, poll. Credits: account, link, user done, account.'}
+    if name not in skills:
+        raise Failure('Unknown skill; use get-skills core.')
+    if not skills[name].get('available', True):
+        return {'status': 'UNAVAILABLE', 'skill': name, **skills[name]['unavailable']}
+    return {'skill': name, 'resourceDirectory': str(ROOT / 'skills' / name), 'scripts': skills[name]['scripts'], 'instructions': (ROOT / 'skills' / name / 'SKILL.md').read_text(encoding='utf-8'),
+            'execution': 'Replace python script.py with nexscope run ' + name + ' --script <listed script> -- . Relative input paths must be absolute because runs use isolated output directories.'}
+
+
+def run(args, client):
+    entry = catalog().get(args.skill)
+    if not entry:
+        raise Failure('Unknown skill.')
+    if not entry.get('available', True):
+        raise Failure('UNAVAILABLE: ' + entry['unavailable']['reason'])
+    script = args.script or (entry['scripts'][0] if len(entry['scripts']) == 1 else None)
+    if script not in entry['scripts']:
+        raise Failure('Choose --script from get-skills output.')
+    context = resolve_auth('browser-account', base=client.base, credential_loader=lambda: client.load('credential'))
+    account = client.api('account', authenticated=True, context=context)
+    folder = Path(args.output).resolve() / str(uuid.uuid4())
+    folder.mkdir(parents=True, mode=0o700)
+    env = context.script_environment()
+    arguments = args.arguments[1:] if args.arguments[:1] == ['--'] else args.arguments
+    # No automatic replay: scripts may create reports, change ads, or consume credits.
+    result = subprocess.run([sys.executable, str(ROOT / 'runner.py'), str(ROOT / 'skills' / args.skill / script), *arguments], cwd=folder, env=env, capture_output=True, text=True)
+    output = context.redact(result.stdout + result.stderr)
+    (folder / 'output.txt').write_text(output)
+    files = list(folder.rglob('*.json'))
+    failures = []
+    for path in files:
+        try:
+            raw = path.read_text()
+            cleaned = context.redact(raw)
+            if raw != cleaned:
+                path.write_text(cleaned)
+            data = json.loads(cleaned)
+            if isinstance(data, dict) and (data.get('error') or data.get('success') is False or data.get('code', 0) not in (0, '0', None) or data.get('errcode', 0) not in (0, '0', None)):
+                failures.append(str(path))
+        except (ValueError, OSError):
+            pass
+    summary = {'status': 'REVIEW_REQUIRED' if result.returncode or failures else 'OUTPUT_READY', 'exitCode': result.returncode,
+               'accountId': account['accountId'], 'output': str(folder), 'errorFiles': failures,
+               'preview': output[:8000], 'rechargeUrl': account['rechargeUrl']}
+    (folder / 'result.json').write_text(json.dumps(summary, indent=2))
+    return summary
+
+
+def export(args):
+    rows = json.loads(Path(args.input).read_text())
+    for key in args.path.split('.') if args.path else []:
+        rows = rows[int(key)] if isinstance(rows, list) else rows[key]
+    if not isinstance(rows, list) or not all(isinstance(row, dict) for row in rows):
+        raise Failure('CSV input must select a list of objects.')
+    fields = list(dict.fromkeys(k for row in rows for k in row))
+    def cell(value):
+        value = json.dumps(value, ensure_ascii=False) if isinstance(value, (dict, list)) else str(value if value is not None else '')
+        return "'" + value if value.lstrip().startswith(('=', '+', '-', '@')) else value
+    with open(args.output, 'x', newline='', encoding='utf-8-sig') as f:
+        writer = csv.writer(f)
+        writer.writerow([cell(k) for k in fields])
+        writer.writerows([cell(row.get(k)) for k in fields] for row in rows)
+    return {'status': 'EXPORTED', 'rows': len(rows), 'file': str(Path(args.output).resolve())}
+
+
+def main():
+    from .capabilities.mock import SCENARIOS
+    parser = argparse.ArgumentParser(prog='nexscope')
+    parser.add_argument('--version', action='version', version=__version__)
+    parser.add_argument('--api-base', default=None)
+    commands = parser.add_subparsers(dest='command', required=True)
+    doctor = commands.add_parser('doctor', help='Local diagnostics; no network or stored credential access.')
+    doctor.add_argument('--profile', choices=['offline', 'independent', 'plugin'], default='offline')
+    doctor.add_argument('--offline', dest='profile', action='store_const', const='offline', help='Alias for --profile offline.')
+    doctor.add_argument('--check-output', help='Probe an existing directory with a temporary file, then remove the probe.')
+    doctor.add_argument('--json', action='store_true', help='JSON is the default output format.')
+    commands.add_parser('get-skills').add_argument('skill', nargs='?', default='core')
+    auth_parser = commands.add_parser('auth')
+    auth_parser.add_argument('action', choices=['login', 'poll', 'status', 'logout'])
+    auth_parser.add_argument('--source-client', choices=['python-cli', 'codex-plugin', 'claude-code'])
+    auth_parser.add_argument('--source-channel', choices=['github', 'marketplace', 'local', 'unknown'], default='unknown')
+    auth_parser.add_argument('--source-entrypoint', choices=['cli', 'plugin', 'report'], default='cli')
+    commands.add_parser('account')
+    capabilities = commands.add_parser('capabilities', help='Offline, versioned pilot capability descriptions.')
+    describe_capability = capabilities.add_subparsers(dest='capability_action', required=True).add_parser('describe')
+    describe_capability.add_argument('capability')
+    describe_capability.add_argument('--json', action='store_true', help='JSON is the default output format.')
+    data = commands.add_parser('data', help='Plan bounded data requests without network or credentials.')
+    data_run = data.add_subparsers(dest='data_action', required=True).add_parser('run')
+    data_run.add_argument('capability')
+    data_run.add_argument('--input', required=True)
+    execution = data_run.add_mutually_exclusive_group(required=True)
+    execution.add_argument('--dry-run', action='store_true')
+    execution.add_argument('--execute', action='store_true', help='Execute an explicit mock scenario or authorized remote scope.')
+    data_run.add_argument('--mock', choices=SCENARIOS)
+    data_run.add_argument('--allow-paid', action='store_true', help='Explicitly authorize bounded remote calls; max-calls is not a monetary cap.')
+    data_run.add_argument('--out', help='New evidence directory for mock execution.')
+    data_run.add_argument('--auth-mode', choices=MODES, default='browser-account')
+    data_run.add_argument('--max-calls', type=int, default=3)
+    data_run.add_argument('--json', action='store_true', help='JSON is the default output format.')
+    workflows = commands.add_parser('workflow', help='Product comparison workflow; remote calls require --execute --allow-paid.')
+    workflow = workflows.add_subparsers(dest='workflow_action', required=True).add_parser('compare')
+    inputs = workflow.add_mutually_exclusive_group(required=True)
+    inputs.add_argument('--asins')
+    inputs.add_argument('--keyword')
+    inputs.add_argument('--resume', help='Import a completed candidates directory; do not repeat its search.')
+    workflow.add_argument('--select-asins')
+    workflow.add_argument('--market', help='Defaults to amazon.com, or the saved marketplace with --resume.')
+    workflow.add_argument('--auth-mode', choices=MODES, help='Defaults to browser-account, or the saved mode with --resume.')
+    workflow.add_argument('--max-calls', type=int, help='Defaults to 4, or the original cumulative budget with --resume.')
+    workflow.add_argument('--out', help='New output directory; never overwrite existing evidence.')
+    workflow.add_argument('--format', choices=['html', 'csv', 'markdown', 'all'], default='html')
+    workflow.add_argument('--mock', choices=SCENARIOS)
+    workflow.add_argument('--allow-paid', action='store_true', help='Explicitly authorize bounded remote calls; never retries.')
+    workflow.add_argument('--json', action='store_true')
+    workflow_execution = workflow.add_mutually_exclusive_group(required=True)
+    workflow_execution.add_argument('--dry-run', action='store_true')
+    workflow_execution.add_argument('--execute', action='store_true')
+    r = commands.add_parser('run')
+    r.add_argument('skill'); r.add_argument('--script'); r.add_argument('--output', default='nexscope')
+    e = commands.add_parser('export')
+    e.add_argument('input'); e.add_argument('--path', default=''); e.add_argument('--output', required=True)
+    report = commands.add_parser('report', help='Offline reports from your own data; no account needed.')
+    reports = report.add_subparsers(dest='report_action', required=True)
+    describe = reports.add_parser('describe', help='Describe input fields, formats and local limits.')
+    describe.add_argument('--schema', action='store_true', help='Print the JSON input schema.')
+    template = reports.add_parser('template', help='Export a blank standard CSV template.')
+    template.add_argument('--format', choices=['csv'], default='csv')
+    template.add_argument('--out', required=True)
+    demo = reports.add_parser('demo', help='Export fictional sample data (not live market data).')
+    demo.add_argument('--format', choices=['csv', 'json'], default='csv')
+    demo.add_argument('--out', required=True)
+    compare = reports.add_parser('compare', help='Compare a user CSV, JSON array or evidence-backed dataset offline.')
+    compare.add_argument('--input', required=True)
+    compare.add_argument('--format', choices=['html', 'csv', 'markdown'], default='html')
+    compare.add_argument('--out', required=True)
+    compare.add_argument('--dry-run', action='store_true', help='Validate and describe outputs without writing.')
+    demos = commands.add_parser('demo', help='Run a complete fictional comparison without credentials or network.')
+    comparison_demo = demos.add_subparsers(dest='demo_action', required=True).add_parser('product-comparison')
+    comparison_demo.add_argument('--out', required=True, help='New output directory.')
+    # Split script arguments explicitly so option names cannot change CLI behavior.
+    argv = sys.argv[1:]
+    tail = argv.index('--') if '--' in argv else len(argv)
+    args = parser.parse_args(argv[:tail])
+    args.arguments = argv[tail + 1:]
+    try:
+        if args.command == 'doctor':
+            from .doctor import diagnose
+            value = diagnose(args.profile, args.check_output, args.api_base)
+        elif args.command == 'get-skills': value = guide(args.skill)
+        elif args.command == 'export': value = export(args)
+        elif args.command == 'report':
+            from .reports.compare import command
+            value = command(args)
+        elif args.command == 'capabilities':
+            from .capabilities.catalog import describe
+            value = describe(args.capability)
+        elif args.command == 'data':
+            from .capabilities.plan import command
+            value = command(args)
+        elif args.command == 'workflow':
+            from .workflows.compare import command
+            value = command(args)
+        elif args.command == 'demo':
+            from .capabilities.mock import executor
+            from .workflows.compare import compare
+            value = compare(executor('browser-account', 'complete', 3), args.out,
+                            asins='B000000001,B000000002,B000000003', mock=True, format='all')
+        else:
+            client = Client(DEFAULT_ORIGIN if args.api_base is None else args.api_base)
+            source = None
+            if args.command == 'auth' and args.source_client:
+                if args.action != 'login':
+                    raise Failure('Source options are supported only for auth login.')
+                source = {'version': 1, 'client': args.source_client, 'channel': args.source_channel,
+                          'campaign': 'cli-data-release', 'entrypoint': args.source_entrypoint}
+            value = run(args, client) if args.command == 'run' else client.auth(args.action if args.command == 'auth' else 'status', source)
+        print(json.dumps(value, ensure_ascii=False, indent=2))
+        return 1 if value.get('status') in ('REVIEW_REQUIRED', 'UNAVAILABLE', 'PARTIAL', 'FAILED', 'INSUFFICIENT_DATA') else 0
+    except DatasetError as e:
+        print(json.dumps({'status': 'INVALID_INPUT', 'message': str(e), 'issues': e.issues}))
+        return 1
+    except (Failure, OSError, ValueError, KeyError) as e:
+        print(json.dumps({'status': 'ERROR', 'message': str(e)}))
+        return 1
+    except Exception as e:
+        # Backend/keyring exceptions may embed secret-bearing request details.
+        print(json.dumps({'status': 'ERROR', 'message': 'Operation failed (' + type(e).__name__ + '). No automatic retry; check the credential store or saved output.'}))
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

nexscope_cli/reports/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Offline reporting; importing this package never connects an account."""

nexscope_cli/reports/compare.py

@@ -0,0 +1,135 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Self-contained HTML reports with input evidence alongside the report."""
+from collections import defaultdict
+from datetime import datetime, timezone
+import hashlib
+from html import escape
+from importlib.resources import files
+import json
+from pathlib import Path
+import re
+from string import Template
+from urllib.parse import quote
+
+from nexscope_cli.core.datasets import FIELDS, read_dataset
+from nexscope_cli.core.evidence import Artifacts, decode, read_bundle
+from .formats import FORMATS, render_csv, render_markdown
+
+
+def resource(name):
+    return files('nexscope_cli.resources').joinpath(name)
+
+
+def display(value):
+    if value is None or value == '':
+        return 'Not provided'
+    if isinstance(value, (dict, list)):
+        value = json.dumps(value, ensure_ascii=False)
+    return escape(str(value))
+
+
+def render(dataset, evidence_name):
+    groups = defaultdict(list)
+    for product in dataset['products']:
+        groups[(product['marketplace'], product['currency'], product['rating_scale'])].append(product)
+    sections = []
+    for (market, currency, scale), products in groups.items():
+        title = f'Market: {display(market)} | Currency: {display(currency)} | Rating scale: {display(scale)}'
+        headers = ''.join(f'<th>{field}</th>' for field in (*FIELDS, 'source_row', 'extra'))
+        rows = []
+        for product in products:
+            cells = []
+            for field in (*FIELDS, 'source_row', 'extra'):
+                value = product[field]
+                content = display(value)
+                if field == 'source_url' and value:
+                    content = f'<a rel="noreferrer noopener" href="{escape(value, quote=True)}">{content}</a>'
+                if field == 'extra' and dataset['sourceType'] in ('mock', 'remote'):
+                    filename = value.get('evidenceFile', '')
+                    if re.fullmatch(r'request-[0-9]+\.json', filename):
+                        href = escape(quote(evidence_name) + '/' + filename, quote=True)
+                        content = f'<a href="{href}">Request evidence</a><br>' + content
+                cells.append(f'<td>{content}</td>')
+            rows.append('<tr>' + ''.join(cells) + '</tr>')
+        sections.append(f'<section><h2>{title}</h2><p>{len(products)} products</p><div class="scroll"><table><thead><tr>{headers}</tr></thead><tbody>{"".join(rows)}</tbody></table></div></section>')
+    missing = sum(any(product[field] is None for field in FIELDS) for product in dataset['products'])
+    notice = 'Source: user_import. Data was supplied by the user and has not been refreshed or independently verified. Bundled samples are fictional.'
+    if dataset['sourceType'] in ('mock', 'remote'):
+        notice = ('MOCK / FICTIONAL DATA: no live service was queried. This report tests the workflow; it is not market research.'
+                  if dataset['sourceType'] == 'mock' else 'REMOTE DATA: retrieved at the recorded times; missing fields are not inferred. Review the request evidence and partial failures.')
+        sections.insert(0, '<section><h2>Collection status: ' + display(dataset['collectionStatus']) + '</h2><p>Failed or skipped products: ' + display(dataset['errors']) + '</p><p>Request accounting: ' + display(dataset['budget']) + '</p></section>')
+    return Template(resource('report.html').read_text(encoding='utf-8')).substitute(
+        count=len(dataset['products']), missing=missing, groups=len(groups),
+        imported=escape(dataset['importedAt']), digest=dataset['inputSha256'],
+        evidence=escape(quote(evidence_name), quote=True), sections='\n'.join(sections),
+        source_notice=escape(notice),
+    )
+
+
+def render_format(dataset, evidence_name, format='html'):
+    if format == 'html':
+        return render(dataset, evidence_name)
+    if format == 'csv':
+        return render_csv(dataset, evidence_name)
+    if format == 'markdown':
+        return render_markdown(dataset, evidence_name)
+    raise ValueError('Choose html, csv or markdown.')
+
+
+def compare(input_path, output_path, dry_run=False, format='html'):
+    dataset, original = read_dataset(input_path)
+    versioned = Path(input_path).suffix.lower() == '.json' and isinstance(decode(original), dict)
+    bundle = read_bundle(Path(input_path).parent) if versioned else None
+    output = Path(output_path).resolve()
+    evidence = output.with_name(output.name + '.evidence')
+    if format not in FORMATS or output.suffix.lower() != FORMATS[format]:
+        raise ValueError('Report format must match its .html, .csv or .md output suffix.')
+    if not output.parent.is_dir():
+        raise NotADirectoryError('Report parent must be an existing directory.')
+    if output.exists() or evidence.exists():
+        raise FileExistsError('Choose a new report path; report or evidence already exists.')
+    if dry_run:
+        return {'status': 'PLAN_READY', 'rows': len(dataset['products']), 'networkCalls': 0,
+                'output': str(output), 'evidence': str(evidence), 'sourceType': dataset['sourceType'], 'format': format}
+    # Exclusive creation prevents replacement of either the input or existing outputs.
+    artifacts = Artifacts(evidence)
+    created = []
+    try:
+        if bundle is not None:
+            for name, raw in bundle.items():
+                if name != 'report-input.json':
+                    artifacts.write_bytes(name, raw)
+        else:
+            artifacts.write_bytes(dataset['inputName'], original)
+            artifacts.write('dataset.json', dataset)
+        artifacts.write('report-input.json', {'inputName': Path(input_path).name,
+                        'inputFile': 'dataset.json' if versioned else dataset['inputName'],
+                        'inputSha256': hashlib.sha256(original).hexdigest(),
+                        'exportedAt': datetime.now(timezone.utc).isoformat()})
+        artifacts.finish()
+        with output.open('x', encoding='utf-8', newline='') as stream:
+            created.append(output)
+            stream.write(render_format(dataset, evidence.name, format))
+    except Exception:
+        for path in reversed(created):
+            path.unlink(missing_ok=True)
+        for name in artifacts.files:
+            (evidence / name).unlink(missing_ok=True)
+        (evidence / 'manifest.json').unlink(missing_ok=True)
+        evidence.rmdir()
+        raise
+    return {'status': 'REPORT_READY', 'rows': len(dataset['products']), 'networkCalls': 0,
+            'file': str(output), 'evidence': str(evidence), 'sourceType': dataset['sourceType'], 'format': format}
+
+
+def command(args):
+    if args.report_action == 'compare':
+        return compare(args.input, args.out, args.dry_run, args.format)
+    if args.report_action == 'describe':
+        name = 'products.schema.json' if args.schema else 'fields.json'
+        return json.loads(resource(name).read_text(encoding='utf-8'))
+    name = 'products-template.csv' if args.report_action == 'template' else 'products-sample.' + args.format
+    with open(args.out, 'xb') as stream:
+        stream.write(resource(name).read_bytes())
+    return {'status': 'EXPORTED', 'file': str(Path(args.out).resolve()), 'networkCalls': 0}

nexscope_cli/reports/formats.py

@@ -0,0 +1,99 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Evidence-linked CSV and Markdown views of the same comparison dataset."""
+from collections import defaultdict
+import csv
+from html import escape
+import io
+import json
+import re
+from urllib.parse import quote
+
+from ..core.datasets import FIELDS
+
+FORMATS = {'html': '.html', 'csv': '.csv', 'markdown': '.md'}
+CONNECT = 'https://github.com/nexscope-ai/nexscope-cli#connect'
+
+
+def text(value):
+    if value is None:
+        return ''
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return str(value)
+
+
+def csv_cell(value):
+    value = text(value)
+    if value.startswith(('\t', '\r', '\n')) or value.lstrip().startswith(('=', '+', '-', '@')):
+        return "'" + value
+    return value
+
+
+def md_cell(value):
+    value = 'Not provided' if value is None or value == '' else text(value)
+    value = escape(value, quote=True)
+    value = re.sub(r'([\\`*_{}\[\]()#+.!|~-])', r'\\\1', value)
+    return value.replace('\r\n', '\n').replace('\r', '\n').replace('\n', '<br>')
+
+
+def grouped(dataset):
+    groups = defaultdict(list)
+    for row in dataset['products']:
+        groups[(row['marketplace'], row['currency'], row['rating_scale'])].append(row)
+    return groups
+
+
+def notice(dataset):
+    if dataset['sourceType'] in ('mock', 'remote'):
+        return ('MOCK / FICTIONAL DATA: no live service queried; not market research.' if dataset['sourceType'] == 'mock'
+                else 'REMOTE DATA: source and retrieval times are in request evidence; missing values are not inferred.')
+    return 'USER IMPORT: supplied data, not refreshed or independently verified; bundled samples are fictional.'
+
+
+def render_csv(dataset, evidence_name):
+    stream = io.StringIO(newline='')
+    columns = ('comparison_group', *FIELDS, 'source_row', 'extra', 'source_type', 'collection_status',
+               'fetched_at', 'cache_hit', 'missing_fields', 'evidence_index', 'input_sha256', 'imported_at',
+               'errors', 'request_accounting', 'data_notice', 'comparison_policy', 'connect_instructions')
+    writer = csv.writer(stream, quoting=csv.QUOTE_ALL, lineterminator='\r\n')
+    writer.writerow(columns)
+    for group_id, rows in enumerate(grouped(dataset).values(), 1):
+        for row in rows:
+            extra = row['extra']
+            values = (group_id, *(row[field] for field in FIELDS), row['source_row'], extra,
+                      dataset['sourceType'], dataset.get('collectionStatus', 'IMPORTED'),
+                      extra.get('fetchedAt') if dataset['sourceType'] in ('mock', 'remote') else None,
+                      extra.get('cacheHit') if dataset['sourceType'] in ('mock', 'remote') else None,
+                      [field for field in FIELDS if row[field] is None],
+                      quote(evidence_name, safe='') + '/dataset.json', dataset['inputSha256'], dataset['importedAt'],
+                      dataset.get('errors', []), dataset.get('budget'), notice(dataset),
+                      'Compare only within the same market/currency/rating-scale group; no ranking or conversion.', CONNECT)
+            writer.writerow([csv_cell(value) for value in values])
+    # BOM helps spreadsheet apps identify UTF-8; exact source values remain in evidence.
+    return '\ufeff' + stream.getvalue()
+
+
+def render_markdown(dataset, evidence_name):
+    groups = grouped(dataset)
+    lines = ['# Product comparison', '', '**' + notice(dataset) + '**', '',
+             f"{len(dataset['products'])} products across {len(groups)} comparable groups.",
+             'Compare only within the same market, currency and rating scale. No cross-group ranking or conversion.', '',
+             'Collection status: ' + md_cell(dataset.get('collectionStatus', 'IMPORTED')), '',
+             'Imported at: ' + md_cell(dataset['importedAt']) + ' (not the observation time).', '',
+             'Input SHA-256: ' + md_cell(dataset['inputSha256']), '',
+             '[Evidence dataset and exact source values](' + quote(evidence_name, safe='') + '/dataset.json)', '',
+             'Failed or skipped products: ' + md_cell(dataset.get('errors', [])), '',
+             'Request accounting: ' + md_cell(dataset.get('budget')), '']
+    fields = (*FIELDS, 'source_row', 'extra')
+    for index, ((market, currency, scale), rows) in enumerate(groups.items(), 1):
+        lines += [f'## Group {index}', '',
+                  'Market: ' + md_cell(market) + ' / Currency: ' + md_cell(currency) + ' / Rating scale: ' + md_cell(scale), '',
+                  '| ' + ' | '.join(fields) + ' |', '| ' + ' | '.join('---' for _ in fields) + ' |']
+        for row in rows:
+            lines.append('| ' + ' | '.join(md_cell(row[field]) for field in fields) + ' |')
+        lines.append('')
+    lines += ['Keep this report with its evidence directory. Missing fields remain unknown.', '',
+              '[Need updated product data? Connect Nexscope](' + CONNECT + ').',
+              'Optional instructions only: this report does not upload inputs or call data services.', '']
+    return '\n'.join(lines)

nexscope_cli/resources/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 Nexscope
+# SPDX-License-Identifier: Apache-2.0
+"""Resources shipped in the wheel, independent of a source checkout."""

nexscope_cli/resources/fields.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "sourceType": "user_import",
+  "formats": [
+    "UTF-8 CSV with unique headers",
+    "UTF-8 JSON array of objects",
+    "Versioned dataset.json with its complete hash-checked evidence directory"
+  ],
+  "limits": {
+    "bytes": 10485760,
+    "products": 10000,
+    "requiresAccount": false,
+    "versionedDatasetBytes": 33554432,
+    "evidenceBundleBytes": 67108864
+  },
+  "fields": {
+    "product_id": "Required non-empty string; unique within marketplace; not restricted to ASINs.",
+    "title": "Required non-empty string. Never generated or inferred.",
+    "marketplace": "Optional market or internal catalog name. Missing is unknown.",
+    "price": "Optional finite non-negative number. Requires currency.",
+    "currency": "Optional uppercase three-letter currency code. No currency conversion.",
+    "rating": "Optional finite non-negative number, no greater than rating_scale.",
+    "rating_scale": "Positive finite number, required with rating. No implicit five-point scale.",
+    "review_count": "Optional non-negative integer. Missing does not mean zero.",
+    "source_url": "Optional HTTP(S) URL without credentials or whitespace.",
+    "observed_at": "Optional ISO 8601 timestamp with timezone. Import time is recorded separately."
+  },
+  "additionalFields": "Preserved as extra metadata; no automatic header mapping.",
+  "errors": "All invalid records are reported; no report is produced until input is corrected. CSV row numbers count logical records including the header; JSON rows are one-based array positions.",
+  "provenance": "Keep the report and its .evidence directory together. It contains the exact input, input SHA-256, import time, source rows and normalized dataset. Missing source/time stays unknown. Re-export preserves the original sourceType, inputName/inputSha256, retrieval times and errors; report-input.json separately records the exact selected input hash. Hashes prove consistency, not server authorship.",
+  "samples": "Bundled inputs are invented examples, not current market data.",
+  "offline": "No authentication, network, or LLM call. Reports contain user data: review them before sharing. The optional Nexscope link opens a guide; it never refreshes data automatically."
+}

nexscope_cli/resources/mock-products.json

@@ -0,0 +1,9 @@
+{
+  "sourceType": "mock",
+  "notice": "Fictional test products. Not live market data.",
+  "products": [
+    {"asin": "B000000001", "title": "Fictional Alpha bottle", "extractedPrice": 20.5, "currency": "USD", "rating": 4.2, "ratingScale": 5, "reviews": 80, "link": "https://example.invalid/product/B000000001"},
+    {"asin": "B000000002", "title": "Fictional Beta bottle", "extractedPrice": 23, "currency": "USD", "rating": 4.5, "ratingScale": 5, "reviews": 40, "link": "https://example.invalid/product/B000000002"},
+    {"asin": "B000000003", "title": "Fictional Gamma bottle", "currency": "USD", "link": "https://example.invalid/product/B000000003"}
+  ]
+}

nexscope_cli/resources/products-sample.csv

@@ -0,0 +1,5 @@
+product_id,title,marketplace,price,currency,rating,rating_scale,review_count,source_url,observed_at
+SAMPLE-001,Sample insulated bottle,own-catalog,19.50,USD,4.2,5,120,https://example.com/products/1,2026-01-01T00:00:00Z
+SAMPLE-002,Sample travel bottle,own-catalog,24.00,USD,4.4,5,95,https://example.com/products/2,2026-01-01T00:00:00Z
+SAMPLE-003,Sample compact bottle,own-catalog,15.00,EUR,8,10,50,https://example.com/products/3,2026-01-01T00:00:00Z
+SAMPLE-004,Sample bottle with missing data,own-catalog,,,,,,,

nexscope_cli/resources/products-sample.json

@@ -0,0 +1,6 @@
+[
+  {"product_id":"SAMPLE-001","title":"Sample insulated bottle","marketplace":"own-catalog","price":19.50,"currency":"USD","rating":4.2,"rating_scale":5,"review_count":120,"source_url":"https://example.com/products/1","observed_at":"2026-01-01T00:00:00Z"},
+  {"product_id":"SAMPLE-002","title":"Sample travel bottle","marketplace":"own-catalog","price":24,"currency":"USD","rating":4.4,"rating_scale":5,"review_count":95,"source_url":"https://example.com/products/2","observed_at":"2026-01-01T00:00:00Z"},
+  {"product_id":"SAMPLE-003","title":"Sample compact bottle","marketplace":"own-catalog","price":15,"currency":"EUR","rating":8,"rating_scale":10,"review_count":50,"source_url":"https://example.com/products/3","observed_at":"2026-01-01T00:00:00Z"},
+  {"product_id":"SAMPLE-004","title":"Sample bottle with missing data","marketplace":"own-catalog"}
+]

nexscope_cli/resources/products-template.csv

@@ -0,0 +1 @@
+product_id,title,marketplace,price,currency,rating,rating_scale,review_count,source_url,observed_at