# 1C Adapter Tools

This directory contains the current agent-facing 1C adapter tools.

The adapter must expose 1C metadata in configurator terms first: object kind,
object name, forms, modules, attributes, tabular sections, commands, events,
and 1C type names. SQL table names, DBNames roles, GUIDs, CAS files, and XML
paths are internal evidence and diagnostics.

## Current Entry Points

Use these commands for normal agent work:

```powershell
python scripts/resolve_1c_object.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --output <ObjectResolutionJson>
python scripts/get_1c_object_brief_context.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --view effective --output <ObjectBriefContextJson>
python scripts/get_1c_object_metadata.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --view effective --output <ObjectMetadataJson>
python scripts/search_1c_object_context.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --text <SearchText> --view effective --search-code --output <ObjectContextSearchJson>
python scripts/get_1c_object_artifacts.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --output <ArtifactsJson>
python scripts/get_1c_object_code_context.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --view effective --output <CodeContextJson>
python scripts/get_1c_module.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --module <ModuleName> --view effective --max-chars <N> --output <ModuleContentJson>
python scripts/get_1c_form_context.py --index <UnifiedRouteIndexJson> --kind <Kind> --name <Name> --form <FormName> --view effective --max-items <N> --output <FormContextJson>
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/compare_1c_saved_state_objects.ps1 -Server <SqlServer> -Database <SqlDatabase> -User <SqlUser> -Password <SqlPassword> -Output <SavedStateObjectComparisonJson>
python scripts/analyze_1c_saved_state_object_details.py --comparison <SavedStateObjectComparisonJson> --config-save-dir <ConfigSaveExportDir> --config-dir <ConfigActiveExportDir> --config-cas-save-dir <ConfigCASSaveExportDir> --config-cas-dir <ConfigCASActiveExportDir> --extension-manifest-summary <ExtensionManifestSummaryJson> --config-cas-all-dir <ConfigCASAllDir> --output <SavedStateObjectDetailJson>
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/build_1c_saved_state_object_report.ps1 -Server <SqlServer> -Database <SqlDatabase> -User <SqlUser> -Password <SqlPassword> -OutputDir <SavedStateReportDir> [-SkipMarkdown]
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/watch_1c_saved_state_once.ps1 -Server <SqlServer> -Database <SqlDatabase> -User <SqlUser> -Password <SqlPassword> -OutputRoot <SavedStateWatchRoot>
python scripts/list_1c_saved_state_watch_runs.py --root <SavedStateWatchRoot> [--limit <N>] [--only-with-delta] [--only-changed] --output <SavedStateWatchRunListJson> [--skip-markdown] [--skip-check]
python scripts/check_1c_saved_state_watch_run_list.py --list <SavedStateWatchRunListJson> --output <SavedStateWatchRunListCheckJson>
python scripts/get_1c_saved_state_latest_watch_run.py --root <SavedStateWatchRoot> [--require-delta] [--require-changed] --output <SavedStateLatestWatchRunJson> [--skip-markdown] [--skip-check]
python scripts/check_1c_saved_state_latest_watch_run.py --latest <SavedStateLatestWatchRunJson> --output <SavedStateLatestWatchRunCheckJson>
python scripts/render_1c_saved_state_latest_watch_run_markdown.py --latest <SavedStateLatestWatchRunJson> --output <SavedStateLatestWatchRunMarkdown>
python scripts/render_1c_saved_state_watch_run_list_markdown.py --list <SavedStateWatchRunListJson> --output <SavedStateWatchRunListMarkdown>
python scripts/check_1c_saved_state_object_report.py --report <SavedStateObjectReportJson> --output <SavedStateObjectReportCheckJson>
python scripts/check_1c_saved_state_watch_once.py --manifest <SavedStateWatchRunJson> --output <SavedStateWatchRunCheckJson>
python scripts/render_1c_saved_state_watch_once_markdown.py --manifest <SavedStateWatchRunJson> --output <SavedStateWatchRunMarkdown>
python scripts/compare_1c_saved_state_object_reports.py --before <PreviousSavedStateObjectReportJson> --after <CurrentSavedStateObjectReportJson> --output <SavedStateObjectReportDeltaJson> [--skip-markdown] [--skip-check]
python scripts/check_1c_saved_state_object_report_delta.py --delta <SavedStateObjectReportDeltaJson> --output <SavedStateObjectReportDeltaCheckJson>
python scripts/render_1c_saved_state_object_report_delta_markdown.py --delta <SavedStateObjectReportDeltaJson> --output <SavedStateObjectReportDeltaMarkdown>
python scripts/list_1c_saved_state_object_changes.py --report <SavedStateObjectReportJson> [--layer base|extension] [--kind <Kind>] [--payload-role <Role>] [--active-missing true|false] --output <SavedStateObjectChangeListJson>
python scripts/get_1c_saved_state_object_change.py --report <SavedStateObjectReportJson> --name <ConfiguratorObjectName> --output <SavedStateObjectChangeJson>
python scripts/render_1c_saved_state_object_report_markdown.py --report <SavedStateObjectReportJson> --output <SavedStateObjectReportMarkdown>
```

Use these commands for task-level investigation and extension patch workflow:

```powershell
python scripts/plan_1c_task_context.py --index <UnifiedRouteIndexJson> --text <TaskText> --view effective --output <TaskContextPlanJson>
python scripts/build_1c_task_evidence.py --index <UnifiedRouteIndexJson> --text <TaskText> --view effective --output <TaskEvidenceBundleJson>
python scripts/propose_1c_task_changes.py --evidence <TaskEvidenceBundleJson> --output <TaskChangeProposalJson>
python scripts/render_1c_task_proposal_markdown.py --proposal <TaskChangeProposalJson> --output <TaskChangeProposalMarkdown>
python scripts/check_1c_change_proposal_safety.py --proposal <TaskChangeProposalJson> --output <TaskChangeProposalSafetyJson>
python scripts/create_1c_patch_workspace.py --proposal <TaskChangeProposalJson> --slug <PatchSlug> --output <PatchWorkspaceCreationJson>
python scripts/check_1c_patch_workspace_integrity.py --workspace <PatchWorkspaceDir> --output <PatchWorkspaceIntegrityJson>
python scripts/check_1c_patch_source_freshness.py --workspace <PatchWorkspaceDir> --output <PatchSourceFreshnessJson>
python scripts/validate_1c_patch_workspace_semantics.py --workspace <PatchWorkspaceDir> --output <PatchWorkspaceSemanticValidationJson>
python scripts/edit_1c_bsl_routine.py --workspace <PatchWorkspaceDir> --relative-path <ManifestBslModuleRelativePath> --operation append|replace|upsert --routine-text-b64 <Utf8Base64BslRoutine> --output <BslRoutineEditJson>
python scripts/edit_1c_form_command.py --workspace <PatchWorkspaceDir> --relative-path <ManifestFormXmlRelativePath> --operation append|replace|upsert --name <CommandName> --title <RussianTitle> --action <BslHandlerName> --output <FormCommandEditJson>
python scripts/edit_1c_form_button.py --workspace <PatchWorkspaceDir> --relative-path <ManifestFormXmlRelativePath> --operation append|replace|upsert --parent-name <ParentFormItemName> --name <ButtonName> --title <RussianTitle> --command-name <ExistingCommandName> --output <FormButtonEditJson>
python scripts/add_1c_form_button_workflow.py --workspace <PatchWorkspaceDir> --form-relative-path <ManifestFormXmlRelativePath> --bsl-relative-path <ManifestFormModuleRelativePath> --operation append|replace|upsert --routine-text-b64 <Utf8Base64BslRoutine> --command-name <CommandName> --command-title <RussianCommandTitle> --command-action <BslHandlerName> --button-parent-name <ParentFormItemName> --button-name <ButtonName> --button-title <RussianButtonTitle> --output <FormButtonWorkflowJson>
python scripts/diff_1c_patch_workspace.py --workspace <PatchWorkspaceDir> --output <PatchWorkspaceDiffJson>
python scripts/create_1c_patch_bundle.py --workspace <PatchWorkspaceDir> --slug <BundleSlug> --output <PatchBundleCreationJson>
python scripts/check_1c_patch_bundle.py --bundle-dir <PatchBundleDir> --output <PatchBundleCheckJson>
python scripts/create_1c_extension_staging_from_bundle.py --bundle-dir <PatchBundleDir> --slug <StagingSlug> --output <ExtensionStagingCreationJson>
python scripts/check_1c_extension_staging.py --staging-dir <ExtensionStagingDir> --output <ExtensionStagingCheckJson>
python scripts/check_1c_extension_runner_config.py --config <ExtensionRunnerConfigJson> --output <ExtensionRunnerConfigCheckJson>
python scripts/create_1c_extension_validation_plan.py --staging-dir <ExtensionStagingDir> --output <ExtensionValidationPlanJson> --markdown-output <ExtensionValidationPlanMarkdown>
python scripts/create_1c_extension_validation_evidence.py --plan <ExtensionValidationPlanJson> --output <ExtensionValidationEvidenceManifestJson>
python scripts/check_1c_extension_validation_evidence.py --plan <ExtensionValidationPlanJson> --output <ExtensionValidationEvidenceCheckJson>
python scripts/check_1c_extension_validation_release.py --plan <ExtensionValidationPlanJson> --output <ExtensionValidationReleaseCheckJson>
python scripts/render_1c_extension_validation_release_markdown.py --release-check <ExtensionValidationReleaseCheckJson> --output <ExtensionValidationReleaseMarkdown>
python scripts/check_1c_patch_preflight.py --workspace <PatchWorkspaceDir> --output <PatchPreflightJson>
python scripts/render_1c_patch_preflight_markdown.py --preflight <PatchPreflightJson> --output <PatchPreflightMarkdown>
```

Use this read orchestrator when object data rows are needed from SQL:

```powershell
python scripts/read_1c_object_view.py --kind <Kind> --name <Name> --view effective --summary <SummaryJson> --validation <ValidationJson> --route-index <RouteIndexJson> --output-dir <OutputDir>
```

Use `--name-b64` and `--kind-b64` when a shell cannot pass Unicode safely.
Saved-state object change lookup also supports `--name-b64`.

## Rebuild And Maintenance

These tools rebuild the evidence used by the current adapter:

```powershell
python scripts/extract_1c_dbnames.py --help
python scripts/build_1c_xml_guid_index.py --help
python scripts/compare_1c_sql_xml_guids.py --help
python scripts/build_1c_unified_object_route_index.py --help
python scripts/build_1c_metadata_from_resolved_object.py --help
python plugins/1c/tools/enrich_structured_metadata_with_dbnames.py --help
python scripts/build_1c_enum_presentation_map.py --help
python scripts/build_1c_sql_read_view.py --help
python scripts/smoke_1c_read_view_kinds.py --help
python plugins/1c/tools/build_sql_read_projection.py --help
./scripts/validate_1c_predicted_columns.ps1 -?
./scripts/execute_1c_sql_read_projection.ps1 -?
./scripts/resolve_1c_sql_read_references.ps1 -?
./scripts/resolve_1c_sql_composite_references.ps1 -?
```

## Current Contract

The current public contract is documented in:

```text
docs/1c-adapter-api-contract.md
docs/1c-write-path-safety.md
docs/1c-sql-format-spec.md
```

Default view is `effective`: base configuration plus active extension overlays.
Use `base` only for main-configuration diagnostics and `extension` only when a
specific extension layer is requested.

Direct SQL writes to `Config`, `ConfigSave`, `ConfigCAS`, `ConfigCASSave`, and
data tables are not part of the safe adapter workflow.